Developer reference
Errors and recovery
Choose the right next action for authentication refusals, conflicts, rate limits and unavailable reads.
Handle HTTP status and the structured error code together. Keep the request identifier for safe diagnostics and avoid copying credentials or full financial payloads into logs.
Status guide
| Status | Typical meaning | Next action |
|---|---|---|
| 400 | Invalid request | Fix malformed fields or unsupported input. |
| 401 | Missing or rejected credential | Verify the session or token. |
| 403 | Scope, admission or origin refusal | Check the exact required permission and request boundary. |
| 404 | Missing or unavailable owned resource | Recheck method, route and owned ID. |
| 409 | Conflict or mismatched retry | Inspect the existing action and original intent. |
| 422 | Invalid domain action | Follow the supplied domain guidance. |
| 429 | Rate limit | Respect Retry-After and reduce polling. |
| 503 | Verification, storage or coherent-read failure | Show unavailable and retry after recovery. |
Reads are not zeros
A failed balance request is not an empty account. Preserve the error/unavailable state rather than returning an attractive default of zero. If a previously loaded result is retained, do not claim it is a fresh verified answer.
Writes need a different retry policy
A timeout can occur after money saved. Keep the original key and identical payload where the idempotency contract applies. Inspect the existing operation before issuing another command. Import recovery continues the existing job.
Report safely
Include the route class, status, safe error code and request identifier. Exclude token secrets, raw statement files and unrelated personal data. A recurring 403 needs diagnosis, not an unbounded retry loop. See rate limits.