docs(spec): document new error codes from AT-5324 epic#500
Conversation
Adds the server-side error codes introduced across the AT-5324 error-audit
epic so SDK clients can encode against them without triggering each error
in production.
New codes documented:
- 401: WALLET_SIGNATURE_MISSING / MALFORMED / BODY_MISMATCH / INVALID
(sparkcore PR #27767, AT-5342)
- 404: UMA_NOT_FOUND (PR #27758, AT-5345)
- 405: METHOD_NOT_ALLOWED (PR #27747, AT-5325)
- 409: CONFLICT, surfaced for duplicate platformCustomerId
(PR #27766, AT-5348)
- 502: VASP_UNREACHABLE / VASP_INVALID_RESPONSE (PR #27758, AT-5345)
Also wires the new 502 response into GET /receiver/uma/{receiverUmaAddress}
and 405 into POST /customers, updates the 404 and 409 response descriptions
to call out the new codes, and re-bundles openapi.yaml +
mintlify/openapi.yaml. No schema redesign — only enum extensions.
See error-audit/FRESH_REVIEW.md cross-cutting observation #3 for the
underlying gap.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
✱ 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
✅ grid-python studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-typescript studio · code · diff
⏳ grid-csharp studio · code · diff
|
|
@greptile review |
Greptile SummaryThis PR is a documentation-only change that extends the OpenAPI spec with 9 new server-side error codes from the AT-5324 error-audit epic, adding two new schemas (
Confidence Score: 5/5Documentation-only change; no application logic, migrations, or API contracts are altered — only enum extensions and new error schema stubs are added. All changes are additive and limited to OpenAPI YAML: new enum values, two new schema files, and updated path-level response blocks. The generated bundles match their sources. No existing behaviour is modified. No files require special attention.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/errors/Error401.yaml | Adds four WALLET_SIGNATURE_* codes to the enum and description table; consistent with existing pattern of shared 401 schema covering all credential-related codes. |
| openapi/components/schemas/errors/Error404.yaml | Appends UMA_NOT_FOUND to the description table and enum list; consistent with existing pattern of adding all 404 codes to the shared schema. |
| openapi/components/schemas/errors/Error405.yaml | New schema for 405 responses with a single METHOD_NOT_ALLOWED code; structure and field ordering match other Error*.yaml files. |
| openapi/components/schemas/errors/Error409.yaml | Adds CONFLICT code with a descriptive example; enum and description table updated consistently. |
| openapi/components/schemas/errors/Error502.yaml | New schema for 502 responses; both VASP_UNREACHABLE and VASP_INVALID_RESPONSE are labelled "Retryable." in the code table, consistent with the path-level "Both are retryable" description. |
| openapi/paths/customers/customers.yaml | Adds 405 response (numerically ordered before 409/500) to both POST and GET operations, and expands 409 description to include the new CONFLICT code. |
| openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml | Expands 404 description with UMA_NOT_FOUND code reference and adds a new 502 response block referencing Error502.yaml with a clear "Both are retryable" note. |
| openapi.yaml | Generated bundle; reflects all source changes correctly. Error405 and Error502 component schemas added; path-level responses updated. |
| mintlify/openapi.yaml | Generated bundle for Mintlify docs; identical changes to openapi.yaml, correctly regenerated via make build. |
Sequence Diagram
sequenceDiagram
participant C as Client
participant G as Grid API
participant V as Counterparty VASP
C->>G: POST /customers (Embedded Wallet)
alt Missing/malformed wallet signature
G-->>C: 401 WALLET_SIGNATURE_MISSING / WALLET_SIGNATURE_MALFORMED
else Body mismatch or invalid signature
G-->>C: 401 WALLET_SIGNATURE_BODY_MISMATCH / WALLET_SIGNATURE_INVALID
else platformCustomerId collision
G-->>C: 409 CONFLICT
else UMA address taken
G-->>C: 409 UMA_ADDRESS_EXISTS
else Unsupported HTTP method
G-->>C: 405 METHOD_NOT_ALLOWED
else Success
G-->>C: 201 Customer created
end
C->>G: "GET /receiver/uma/{receiverUmaAddress}"
G->>V: UMA lookup request
alt Network/DNS/TLS failure
V--xG: unreachable
G-->>C: 502 VASP_UNREACHABLE (retryable)
else Invalid/unparseable UMA response
V-->>G: malformed response
G-->>C: 502 VASP_INVALID_RESPONSE (retryable)
else Address not found at VASP
V-->>G: not found
G-->>C: 404 UMA_NOT_FOUND
else Success
V-->>G: receiver info
G-->>C: 200 Receiver details
end
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}
- Mark VASP_INVALID_RESPONSE as Retryable in Error502 schema to match
path-level description
- Reorder 405 before 409 in POST /customers responses for numeric ordering
- Document 405 METHOD_NOT_ALLOWED on GET /customers as well
- Add trailing newline to receiver_uma_{receiverUmaAddress}.yaml
|
@greptile review |
1 participant
Summary
Documents the ~11 server-side error codes added across the AT-5324 error-audit epic so SDKs and integrators have a way to learn them other than triggering them in production. Cross-cutting observation #3 in
error-audit/FRESH_REVIEW.mdflagged the gap.Codes documented
WALLET_SIGNATURE_MISSINGWALLET_SIGNATURE_MALFORMEDWALLET_SIGNATURE_BODY_MISMATCHWALLET_SIGNATURE_INVALIDUMA_NOT_FOUNDMETHOD_NOT_ALLOWEDCONFLICT(newly surfaced for duplicateplatformCustomerId)VASP_UNREACHABLEVASP_INVALID_RESPONSENOT_IMPLEMENTED(501) was already documented; no change needed.Files changed
openapi/components/schemas/errors/Error401.yaml— adds the fourWALLET_SIGNATURE_*codesopenapi/components/schemas/errors/Error404.yaml— addsUMA_NOT_FOUNDopenapi/components/schemas/errors/Error409.yaml— addsCONFLICTopenapi/components/schemas/errors/Error405.yaml(new) —METHOD_NOT_ALLOWEDopenapi/components/schemas/errors/Error502.yaml(new) —VASP_UNREACHABLE,VASP_INVALID_RESPONSEopenapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml— adds 502 response, expands 404 descriptionopenapi/paths/customers/customers.yaml— adds 405 response, expands 409 description to mentionCONFLICTopenapi.yaml+mintlify/openapi.yaml— re-bundledConstraints honored
make buildregenerated the bundle;make lintpasses (warnings only, all pre-existing).Test plan
make buildsucceedsmake lintpasses (no new errors, pre-existing warnings only)grep -E "WALLET_SIGNATURE|UMA_NOT_FOUND|VASP_|METHOD_NOT_ALLOWED|CONFLICT" openapi.yaml)Related: epic AT-5324,
error-audit/FRESH_REVIEW.md.