docs(spec): correct quote expiresAt window, document 501 on /cards, add 429 to verify#498
docs(spec): correct quote expiresAt window, document 501 on /cards, add 429 to verify#498jklein24 wants to merge 2 commits into
Conversation
…dd 429 to verify
Updates several OpenAPI accuracy gaps surfaced by the Grid error audit
(parent epic AT-5324):
- Quote.expiresAt was documented as 1-5 minutes; probes show window
varies by rail and corridor. Replace with rail-aware description and
the instruction to rely on the timestamp rather than a fixed window.
- GET /cards (and /cards/{id}) returns 501 in dev today; document the
response so SDK clients can handle it without surprise.
- POST /auth/credentials/{id}/verify can return 429 with Retry-After;
document the rate-limit envelope and header.
- DELETE /auth/sessions/{id} description clarified to set expectations
about 404 semantics on already-revoked sessions.
Schema additions (supportedNetworks on InternalAccount, network field
on RealtimeFundingQuoteSource) deferred — those are API design changes,
not doc fixes, and warrant their own tickets.
Refs AT-5351
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This stack of pull requests is managed by Graphite. Learn more about stacking. |
✱ Stainless preview builds for gridThis PR will update the cli csharp go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
|
Greptile SummaryThis PR makes accuracy fixes to the OpenAPI spec based on a Grid error audit — documenting previously-undocumented error responses and correcting the
Confidence Score: 5/5Pure documentation accuracy fixes — no logic changes, no schema structural changes, and all referenced schemas (Error429, Error501) already exist in the compiled bundle. All changes are additive response-code documentation aligned with the deployed server's actual behavior. Both bundled files were regenerated via make build rather than edited directly. The Error429 schema repositioning is cosmetic and the definition is unchanged. No previous-thread issues remain unresolved in the current diff. No files require special attention.
|
| Filename | Overview |
|---|---|
| openapi/paths/auth/auth_credentials_{id}_verify.yaml | Adds 429 response with Retry-After header and $ref to existing Error429 schema — accurate and complete. |
| openapi/paths/auth/auth_sessions_{id}.yaml | Adds 404 semantics paragraph to DELETE description; compound adjective "already-revoked" is on a single line so folded-scalar rendering is correct. |
| openapi/paths/cards/cards.yaml | Adds 501 to both POST /cards and GET /cards with correct $ref to existing Error501 schema. |
| openapi/paths/cards/cards_{id}.yaml | Adds 501 to both GET /cards/{id} and PATCH /cards/{id} — covers all card endpoints on this path. |
| openapi/components/schemas/quotes/Quote.yaml | Replaces hard-coded "1-5 minutes" claim with rail-aware description; wording is accurate and correctly instructs clients to rely on the timestamp. |
| openapi.yaml | Generated bundle updated via make build — mirrors all source changes and repositions Error429 schema (cosmetic reordering, schema definition unchanged). |
| mintlify/openapi.yaml | Mintlify bundle updated via make build — identical semantic changes to openapi.yaml, including Error429 schema reorder. |
Sequence Diagram
sequenceDiagram
participant C as Client
participant G as Grid API
Note over C,G: POST /auth/credentials/{id}/verify — now documents 429
C->>G: "POST /auth/credentials/{id}/verify"
alt too many attempts
G-->>C: 429 RATE_LIMITED + Retry-After: N
C->>C: wait N seconds
C->>G: retry POST
end
G-->>C: 200 OK
Note over C,G: DELETE /auth/sessions/{id} — 404 semantics clarified
C->>G: "DELETE /auth/sessions/{id}"
alt session expired or already revoked
G-->>C: 404 (resource not found — safe, idempotent)
else active session
G-->>C: 202 payloadToSign
C->>G: DELETE (with Grid-Wallet-Signature)
G-->>C: 204 No Content
end
Note over C,G: Card endpoints — now document 501
C->>G: GET /cards
alt card issuer not configured
G-->>C: 501 NOT_IMPLEMENTED
else cards enabled
G-->>C: 200 OK
end
Reviews (3): Last reviewed commit: "address greptile review feedback (greplo..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
- Add 501 NOT_IMPLEMENTED response to PATCH /cards/{id} for parity with
the GET endpoints (same card-issuer dependency).
- Reflow the auth_sessions_{id} DELETE description so the YAML folded
scalar doesn't render 'already- revoked' with a space after the hyphen.
|
@greptile review |
1 participant
Summary
Spec/docs accuracy fixes from the Grid error audit (epic AT-5324):
Quote.expiresAt: replace "1-5 minutes" claim with rail-aware wordingGET /cardsandGET /cards/{id}: add documented501 NOT_IMPLEMENTEDresponse (matches deployed server)POST /auth/credentials/{id}/verify: document429response andRetry-AfterheaderDELETE /auth/sessions/{id}: clarify 404 semantics in descriptionSchema additions (supportedNetworks, RealtimeFundingQuoteSource.network) deferred — those are API design changes, not doc fixes.
Why
Audit observed integrators getting surprised by:
expiresAt2+ days out vs. docs claiming 5 minGET /cardsreturning 501 (undocumented)Retry-Afterguidance on verify rate-limitsTest plan
make buildcleanmake lintcleanRefs AT-5351 under epic AT-5324