Errors

Errors use a JSON envelope with a stable upper-case code and human-readable message.

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "missing X-Api-Key header"
  }
}

Do not parse message for control flow. Use HTTP status and error.code for programmatic handling.

Common Status Codes

Status	Meaning	Action
`400`	Invalid request	Fix parameters, filters, enum values, or body fields
`401`	Missing or invalid API key	Check `X-Api-Key`
`402`	Insufficient available balance	Reconcile balances and reduce or defer the request
`403`	Access or account requirement not met	Confirm key access and account readiness
`404`	Resource not found	Verify the public identifier and account context
`409`	Conflict	Check idempotency, duplicate intent, or current resource state
`422`	Valid JSON that cannot be processed	Correct the destination or business input
`429`	Too many requests	Back off and retry later
`503`	Service temporarily unavailable	Use bounded backoff and preserve retry safety

Retry Guidance

Class	Retry?	Notes
`400`	No	The request is malformed or semantically invalid
`401`	No	Fix credentials or environment
`402`	No	Restore available balance or submit a smaller valid request
`403`	No	Fix key access or account readiness
`404`	Usually no	Retry only if you expect eventual visibility after a recent action
`409`	Depends	For idempotency conflicts, read the existing order or create a new intent
`422`	No	Correct the request’s business input
`429`	Yes, after backoff	Slow down the caller and keep idempotency keys stable for order writes
`5xx`	Yes, bounded	Retry with backoff while preserving the operation’s idempotency rules

For a signed withdrawal retry, keep the exact body and its business idempotency_key, then generate a new timestamp, nonce, and signature for the new HTTP attempt. See Withdrawals. Do not apply generic retry logic that changes the withdrawal body.

Required Headers

Use X-Api-Key on authenticated endpoints. Use Content-Type: application/json on JSON writes. Use Idempotency-Key on order create, cancel, and replace requests.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Common Status Codes

Retry Guidance

Required Headers

​Common Status Codes

​Retry Guidance

​Required Headers

Common Status Codes

Retry Guidance

Required Headers