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 corrects documentation accuracy issues surfaced by the Grid error audit. All changes are spec/doc only — no server logic is modified.
Confidence Score: 5/5Safe to merge — all changes are spec documentation only with no server logic modifications. Every changed file is an OpenAPI YAML spec or its bundled derivative. The additions (501 on card endpoints, 429 on verify, 404 semantics on session delete, rail-aware quote expiry) match the described deployed server behavior. The bundled openapi.yaml and mintlify/openapi.yaml are consistent with the modular source files. No files require special attention.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/quotes/Quote.yaml | Updated expiresAt description to rail-aware wording, replacing the inaccurate "1-5 minutes" claim with a timestamp-first approach that lists rail-specific windows. |
| openapi/paths/auth/auth_credentials_{id}_verify.yaml | Added 429 response with Retry-After header documentation; Retry-After header is not marked required:true, which understates server behavior on 429 responses. |
| openapi/paths/auth/auth_sessions_{id}.yaml | Added operation-level description clarifying 404 semantics to cover expired and previously-revoked sessions, not just "not found". |
| openapi/paths/cards/cards.yaml | Added 501 NOT_IMPLEMENTED to both POST /cards and GET /cards responses; correct and consistent with deployed server behavior. |
| openapi/paths/cards/cards_{id}.yaml | Added 501 NOT_IMPLEMENTED to both GET /cards/{id} and PATCH /cards/{id}; all card endpoint operations now have 501 coverage. |
| openapi.yaml | Bundled spec updated with all modular changes; Error429 schema moved earlier in components (reorder only, content identical). |
| mintlify/openapi.yaml | Mintlify copy of bundled spec updated in lockstep with openapi.yaml; changes are identical. |
Sequence Diagram
sequenceDiagram
participant C as Client
participant G as Grid API
Note over C,G: POST /auth/credentials/{id}/verify (with 429 now documented)
C->>G: "POST /auth/credentials/{id}/verify"
alt Success
G-->>C: 200 OK (AuthSession + encryptedSessionSigningKey)
else Too many attempts
G-->>C: 429 RATE_LIMITED + Retry-After: N
Note over C: Back off N seconds
C->>G: "POST /auth/credentials/{id}/verify (retry)"
G-->>C: 200 OK
end
Note over C,G: DELETE /auth/sessions/{id} - 404 semantics clarified
C->>G: "DELETE /auth/sessions/{id} (no headers)"
G-->>C: 202 (payloadToSign + requestId)
C->>G: "DELETE /auth/sessions/{id} (Grid-Wallet-Signature + Request-Id)"
alt Session still active
G-->>C: 204 No Content
else Session expired or already revoked
G-->>C: 404 (resource state, not a client error)
end
Note over C,G: GET /cards or GET /cards/{id} - 501 now documented
C->>G: GET /cards
alt Cards enabled
G-->>C: 200 OK
else No card issuer configured
G-->>C: 501 NOT_IMPLEMENTED
end
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
openapi/paths/auth/auth_credentials_{id}_verify.yaml:118-122
The `Retry-After` header is documented here but not marked as `required: true`. Since the 429 description explicitly tells clients to "back off and retry after the interval indicated by the `Retry-After` response header," the spec implies the header is always present on a 429. Omitting `required: true` means generated SDK clients and validators may treat the header as optional and skip implementing the backoff, defeating the purpose of documenting it.
```suggestion
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
required: true
schema:
type: integer
```
Reviews (2): 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