Errors and recovery
Errors include error.code, error.message and error.request_id; validation may add field_errors. Keep X-Request-Id for support, without keys or personal data.
| Code | What to do |
|---|---|
| 401 INVALID_API_KEY | Check the key, revocation or chosen expiry in the cabinet. Indefinite keys need no renewal. |
| 403 INSUFFICIENT_SCOPE | Check scopes, locations, financial authorization/binding and the business export window. |
| 404 | Check the authorized resource. A native ledger ID is not automatically a financial ID. |
| 409 IDEMPOTENCY_CONFLICT | Recover the original UUID and body; never change the UUID to bypass an uncertain result. |
| 409 STALE_QUOTE / QUOTE_EXPIRED | Read the status and obtain a new quote before a new verified attempt. |
| 409 STALE_REVISION / CARD_RESERVED | Read the checkout and inspect the existing operation; do not start another payment. |
| 409 REFUND_ALLOCATION_MISMATCH | Use original gross values and cumulative allocations, including any returned noneligible cash. |
| 410 CURSOR_EXPIRED | Rebuild the full snapshot. Retired endpoints have their own 410 codes. |
| 422 INVALID_CURSOR / VALIDATION_ERROR | Fix parameters. For configuration lists, restart at page 1 after the one-hour cursor expires. |
| 423 SERVICE_SUSPENDED | Financial operations are unavailable; resolve service status in the cabinet. |
| 429 RATE_LIMITED | Honor Retry-After and spread requests within the shared connection budget. |
| 503 or timeout | Preserve UUID and body, back off and read/reconcile an uncertain operation before retrying. |