Error Codes

Use HTTP status, error.code, and error.action together. The table lists common groups; endpoint-specific errors remain authoritative in the API Reference.

HTTP	Representative codes	Typical action
400	MISSING_REQUIRED_FIELD, INVALID_FIELD_VALUE	Fix the request
401	INVALID_API_KEY, INVALID_TIMESTAMP, NONCE_REPLAYED, INVALID_SIGNATURE	Correct authentication
403	FORBIDDEN, ACCOUNT_NOT_ACTIVE	Verify access or state
404	ACCOUNT_NOT_FOUND, DEPOSIT_NOT_FOUND, WITHDRAWAL_NOT_FOUND, LEDGER_NOT_FOUND	Verify environment and ID
409	CONFLICT, WITHDRAWAL_NOT_CANCELLABLE	Recover or resolve existing state
422	INVALID_AMOUNT, INSUFFICIENT_BALANCE, AMOUNT_BELOW_MINIMUM, AMOUNT_ABOVE_MAXIMUM	Correct amount or balance
429	RATE_LIMITED	Bounded retry later
503	SERVICE_MAINTENANCE, NETWORK_UNAVAILABLE, ASSET_UNAVAILABLE	Bounded retry later
500	INTERNAL_ERROR	Recover mutation result, then contact support

Unknown codes must fail safely and be recorded. message is for people and may be localized. Include request_id in support reports, never credentials.

Action handling

RETRY_LATER does not mean every request can be replayed. Retry eligible reads with backoff. For a financial create request, first recover by client_request_id. ADJUST_AMOUNT, INCREASE_BALANCE, REQUEST_ACCESS, and similar actions require a new customer or operational decision.

Treat an unknown code or action as non-retryable until reviewed. Preserve HTTP status, safe response metadata, and request correlation so a newly introduced server code does not cause a retry storm.