[grid-api] Document the 202 processing-pending / retry-same-request contract (SP-3579) - #820
[grid-api] Document the 202 processing-pending / retry-same-request contract (SP-3579)#820carsonp6 wants to merge 1 commit into
Conversation
…st contract (SP-3579)
Several Embedded Wallet sync endpoints run their underlying wallet
operation optimistically in line and can fall back to asynchronous
processing. When that happens they return a non-terminal HTTP 202 with
`{ "status": "PENDING" }`; the caller must re-send the identical request
(same method, path, body, and headers) until it resolves to a terminal
200/201/204.
Add a reusable `ProcessingPendingResponse` schema (status: PENDING) and
reference it as a 202 on each affected endpoint:
- POST /auth/credentials/{id}/verify (login: OTP / OAuth / passkey)
- POST /auth/credentials/{id}/challenge (OTP init / passkey challenge)
- POST /auth/sessions/{id}/refresh (session refresh)
- POST /auth/credentials (add credential)
- PATCH /customers/{customerId} (contact update: email / phone)
- POST /auth/delegated-keys (delegated-key create)
- DELETE /auth/delegated-keys/{id} (delegated-key revoke)
- POST /internal-accounts/{id}/export (wallet export)
Endpoints that already return a 202 signed-retry challenge now document an
anyOf of that challenge or the pending marker, via named wrapper schemas
(spectral forbids inline response schemas and oneOf without a
discriminator). Document the retry contract in the endpoint descriptions
and the Global Accounts authentication guide.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
github-actions
Bot
added
the
breaking-change
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-cli studio · code · diff
✅ grid-php studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
1 participant
What
Documents the 202 processing-pending / retry-same-request contract on the Embedded Wallet sync endpoints. This is the ramp prerequisite for the state-machine migration: the underlying wallet operation now runs optimistically in line and can fall back to asynchronous processing. When it does, the endpoint returns a non-terminal
202with{ "status": "PENDING" }, and the caller must re-send the identical request (same method, path, body, and headers) until it resolves to a terminal200/201/204(or an error).Docs-only change to the spec + integrator docs. No behavior change here; the server behavior lands separately, and the webdev client regen from this source is a follow-on after merge.
Reusable component
components/schemas/common/ProcessingPendingResponse.yaml— body carrying the requiredstatus: PENDINGfield plus the authoritative "still processing — re-send the identical request" description.Affected endpoints (all got the 202)
POST /auth/credentials/{id}/verify(login: OTP / OAuth / passkey)POST /auth/credentials/{id}/challenge(OTP init / passkey challenge)POST /auth/sessions/{id}/refresh(session refresh)POST /auth/credentials(add credential)PATCH /customers/{customerId}(contact update: email / phone)POST /auth/delegated-keys(delegated-key create)DELETE /auth/delegated-keys/{id}(delegated-key revoke)POST /internal-accounts/{id}/export(wallet export)(
challengecovers both the passkey challenge and the OTP-init/send path.)Response-shape modeling decision (please sanity-check)
Six of these endpoints already return a
202— the existing signed-retry challenge (payloadToSign+requestId). Since an operation has only one202, the pending marker has to share it. The two bodies are a non-tagged union with no shared discriminator property, and the repo's spectral config forbids inline response schemas (no-inline-response-schema) andoneOfwithout a discriminator (oneOf-must-have-discriminator, "use anyOf for non-tagged unions"). So each such202now$refs a small namedanyOfwrapper:common/SignedRequestChallengeOrProcessingPending.yaml(refresh, contact update, export)auth/AuthSignedRequestChallengeOrProcessingPending.yaml(verify, add credential)auth/DelegatedKeySignedRequestChallengeOrProcessingPending.yaml(delegated-key create)The two clean endpoints (challenge, delegated-key revoke)
$refProcessingPendingResponsedirectly. The reusable piece is modeled as a schema rather than acomponents.responsesentry to match repo convention (there are nocomponents.responsesin this spec; all reuse is via schema files).Docs
Retry contract documented in each endpoint description and in the Global Accounts authentication guide (
snippets/global-accounts/authentication.mdx, new "Still-processing responses (202 PENDING)" section under the shared signed-retry pattern — the session and export guides already link there).Verification
make build— cleanmake lint(redocly + spectral) — clean (0 errors; remaining warnings/infos are pre-existing on unrelated schemas)