feat: document SCA_SESSION_REQUIRED (409) and ACCOUNT_LOCKED (423) on quote authorize

[jklein24]

Summary

Two error codes the API already returns were missing from the spec, so a generated client rejected the response instead of surfacing the code.

• SCA_SESSION_REQUIRED added to the Error409 code enum. The API returns this with HTTP 409 when the customer's Strong Customer Authentication login session is missing or expired. Because it was absent from the enum, a generated client raised a validation error while deserializing the response — so an integrator got an opaque failure rather than a code they could act on. It is deliberately distinct from a 401, which means the platform's API credentials were rejected: a 401 is not customer-recoverable, whereas SCA_SESSION_REQUIRED means "re-authenticate the customer, then retry".

• POST /quotes/{quoteId}/authorize now documents 409 SCA_SESSION_REQUIRED and 423 ACCOUNT_LOCKED. This is the endpoint that surfaces both. Its 409 description previously covered only the "SCA not required / no pending challenge" cases, and it declared no 423 at all — even though the endpoint returns ACCOUNT_LOCKED when the customer's login is temporarily locked after too many failed authorization attempts. Error423 already existed and needed no change; this just references it.

Both changes are additive and non-breaking, so info.version stays 2025-10-13.

Known limitation this does not fix

While verifying the above against the running implementation, I found that the error envelope does not match what the ErrorNNN schemas declare. The API sends:

{"code": "SCA_SESSION_REQUIRED", "reason": "..."}

but every ErrorNNN schema requires status, code, and message. So a generated Python client rejects a real error body on status (int_type) and message (string_type) regardless of this change:

('status',)  | int_type    | Input should be a valid integer
('message',) | string_type | Input should be a valid string

This is pre-existing and applies to every documented error response across the spec, not just the two codes here — it is not introduced by this PR, and this PR is still a strict improvement (the enum is the published contract, and integrators reading the raw JSON body now have the code documented). But it does mean the typed-model path is not yet usable for error handling, so reconciling the envelope is worth its own change. Two options, both spec-wide decisions I did not want to make unilaterally: make the server emit status/message, or change the schemas to match reality (reason, and status not required).

Relatedly, Error423's own description points readers at details.lockedUntil / details.failedAttempts, but no error path populates them — those fields appear only on the 200 body of POST /sca/record-event. I left that description alone rather than expand this PR's scope, and worded the new 423 on the authorize endpoint to promise only what is actually sent.

Test plan

• make lint exits 0 (Redocly + Spectral, --fail-severity=error); the 630 remaining findings are pre-existing warnings/infos, 0 errors.
• make build rebundled openapi.yaml and mintlify/openapi.yaml; re-running it is a no-op, so the committed bundles byte-match the build output.
• Confirmed against the running implementation that both codes are genuinely emitted on this endpoint, each covered by a test asserting the status/code pair at the HTTP boundary — the 423 case is newly covered by a test added alongside this change. The 423 body was captured directly to confirm the wording matches what is sent.
• Diff is 4 files: 2 spec sources + the 2 generated bundles.

Public

Documents two error codes the Grid API already returns: SCA_SESSION_REQUIRED (409) is added to the shared Error409 enum, and POST /quotes/{quoteId}/authorize now documents both it and 423 ACCOUNT_LOCKED.

Original PR: #759

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored		Jul 29, 2026 6:10am
grid-wallet-demo	Ignored		Jul 29, 2026 6:10am

[akanter]

• feat: document SCA_SESSION_REQUIRED (409) and ACCOUNT_LOCKED (423) on quote authorize #761 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

feat(api): add 423 response and SCA_SESSION_REQUIRED error code to quote authorization

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

⚠️ grid-openapi studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

⚠️ grid-go studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ⏭️ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@64ca665ae45c442d51738daa6baaa4cd69915bf0

⚠️ grid-kotlin studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

⚠️ grid-python studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ✅ → build ⏭️ → lint ⏭️ → test ❗

✅ grid-typescript studio · conflict

Your SDK build had at least one note diagnostic.

✅ grid-php studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️ grid-cli studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-30 01:25:26 UTC

[greptile-apps]

Greptile Summary

⚔️☠️🎸 THE SCA ERROR CODE DRAGON NOW ROARS IN THE OPENAPI ABYSS! 🎸☠️⚔️

• Adds SCA_SESSION_REQUIRED to the shared Error409.code enum and documentation.
• Documents 409 SCA_SESSION_REQUIRED and 423 ACCOUNT_LOCKED responses for quote authorization.
• Regenerates the root and Mintlify OpenAPI bundles from the modular source.

Confidence Score: 5/5

The PR appears safe to merge, with the source specification and both generated bundles consistently documenting the existing error responses.

The shared error enum, endpoint response definitions, and generated artifacts follow the repository’s established OpenAPI conventions without introducing a concrete contract, build, or security failure.

Important Files Changed

Filename	Overview
openapi/components/schemas/errors/Error409.yaml	Adds the existing SCA_SESSION_REQUIRED backend error to the shared 409 error-code contract using the repository’s established status-level enum convention.
openapi/paths/quotes/quotes_{quoteId}_authorize.yaml	Documents the missing-session 409 recovery flow and adds the existing Error423 response for temporarily locked customer logins.
openapi.yaml	Regenerated root bundle accurately mirrors the modular path and error-schema changes.
mintlify/openapi.yaml	Regenerated Mintlify bundle remains synchronized with the root OpenAPI bundle.

_{Reviews (1): Last reviewed commit: "feat: document SCA_SESSION_REQUIRED (409..." | Re-trigger Greptile}