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
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
|
@greptile review |
Greptile SummaryThis PR extends the OpenAPI spec with seven new error codes from the AT-5324 error-audit epic, adding descriptive documentation so SDK consumers and integrators can discover them without triggering them in production.
Confidence Score: 5/5Safe to merge — all changes are additive documentation with no semantic or runtime impact. The changes extend enum values and description text in YAML schemas only; no application logic is touched. The one notable concern — UMA_NOT_FOUND documenting a code the server does not yet emit — is explicitly acknowledged by the author as a deliberate, deferred decision, and cannot cause a runtime regression in a documentation-only repo. openapi/components/schemas/errors/Error404.yaml and openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml — both reference UMA_NOT_FOUND, which the author acknowledges the server does not currently emit.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/errors/Error401.yaml | Adds four WALLET_SIGNATURE_* codes (MISSING, MALFORMED, BODY_MISMATCH, INVALID) with clear descriptions; enum and description table are in sync. |
| openapi/components/schemas/errors/Error404.yaml | Adds UMA_NOT_FOUND to the global 404 schema; the code originates from the cancelled AT-5345 epic and the server does not currently emit it, making the enum entry potentially misleading to integrators. |
| openapi/components/schemas/errors/Error405.yaml | New schema for METHOD_NOT_ALLOWED; structure is consistent with all other ErrorNNN schemas in the directory. |
| openapi/components/schemas/errors/Error409.yaml | Adds CONFLICT code with a descriptive example; enum and description table are in sync. |
| openapi/paths/customers/customers.yaml | Adds 405 response (in correct numerical order) to both POST and GET operations, and expands the 409 description to name both conflict codes. |
| openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml | Updates 404 description to reference UMA_NOT_FOUND and adds the previously-missing trailing newline; UMA_NOT_FOUND is from cancelled AT-5345 and not currently emitted by the server. |
| openapi.yaml | Re-bundled output; matches mintlify/openapi.yaml identically, consistent with make build output. |
| mintlify/openapi.yaml | Re-bundled Mintlify copy; identical changes to openapi.yaml as expected from the build step. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[API Request] --> B{HTTP Status}
B -->|401 Unauthorized| C[Error401]
C --> C1[UNAUTHORIZED]
C --> C2[INVALID_SIGNATURE]
C --> C3[WALLET_SIGNATURE_MISSING new]
C --> C4[WALLET_SIGNATURE_MALFORMED new]
C --> C5[WALLET_SIGNATURE_BODY_MISMATCH new]
C --> C6[WALLET_SIGNATURE_INVALID new]
B -->|404 Not Found| D[Error404]
D --> D1[TRANSACTION_NOT_FOUND]
D --> D2[USER_NOT_FOUND]
D --> D3[... other codes ...]
D --> D4[UMA_NOT_FOUND new - not yet emitted]
B -->|405 Method Not Allowed| E[Error405 new]
E --> E1[METHOD_NOT_ALLOWED]
B -->|409 Conflict| F[Error409]
F --> F1[UMA_ADDRESS_EXISTS]
F --> F2[TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL]
F --> F3[EMAIL_OTP_EMAIL_ALREADY_EXISTS]
F --> F4[EMAIL_OTP_CREDENTIAL_SET_CHANGED]
F --> F5[CONFLICT new]
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/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml:52-59
**UMA_NOT_FOUND documented but server doesn't emit it**
The PR description explicitly states that `UMA_NOT_FOUND` "is in the same boat" as the removed 502 codes — it originates from the cancelled AT-5345 epic and the server does not currently emit it. The path description now tells integrators that a 404 from this endpoint will carry the `UMA_NOT_FOUND` code, but in practice the server returns a different code (or no structured code at all) for this case. SDK consumers who generate error-handling stubs from this spec will write `if (code === 'UMA_NOT_FOUND')` and never match in production. If the "pending separate decision" is to eventually emit this code, that's fine — but consider adding a note that the code is provisional, or holding the 404 description update until the decision is resolved.
Reviews (3): Last reviewed commit: "Remove 502 / VASP_UNREACHABLE / VASP_INV..." | 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 |
Dropping the 502 documentation since AT-5345 (the server-side change
that would have introduced these codes) was closed without merging.
The spec shouldn't document codes the server doesn't emit.
- Delete openapi/components/schemas/errors/Error502.yaml
- Drop the '502' response from POST /receiver/uma/{receiverUmaAddress}
- Re-bundle openapi.yaml + mintlify/openapi.yaml
1 participant
Summary
Documents the 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)NOT_IMPLEMENTED(501) was already documented; no change needed.The 502 codes (
VASP_UNREACHABLE,VASP_INVALID_RESPONSE) were initially included but have been removed — AT-5345 was cancelled and the server doesn't emit them.UMA_NOT_FOUNDis in the same boat (originally from AT-5345) but is being left in for now pending a separate decision.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/paths/customers/customers.yaml— adds 405 response, expands 409 description to mentionCONFLICTopenapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml— expands 404 descriptionopenapi.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|METHOD_NOT_ALLOWED|CONFLICT" openapi.yaml)Related: epic AT-5324,
error-audit/FRESH_REVIEW.md.