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. A request that fails before it can be parsed does not get the envelope. A missing or wrong Content-Type header returns 415, malformed JSON returns 400, and an unknown or missing body field returns 422, each with a plain-text body. Branch on the HTTP status first, then on error.code when a JSON body is present.

Error Codes

error.code is one of a fixed set of upper-case values. The ones you are most likely to handle:

Code	Typical status	Meaning
`VALIDATION_FAILED`	`400`	A field, filter, or enum value is invalid
`UNAUTHORIZED`	`401`	Missing or invalid API key
`SIGNING_REQUIRED`, `INVALID_SIGNATURE`, `INVALID_TIMESTAMP`	`401`	A signed withdrawal request failed verification
`INSUFFICIENT_BALANCE`	`402`	Available balance cannot cover the request
`FORBIDDEN`	`403`	Missing scope on an ordinary route, or an account requirement such as KYB is not met
`MISSING_SCOPE`	`403`	Missing scope on a signed withdrawal route
`NOT_FOUND`	`404`	Unknown identifier or outside your account
`CONFLICT`	`409`	Current resource state prevents the change
`REPLAYED_REQUEST`	`409`	A signed nonce was reused
`IDEMPOTENCY_CONFLICT`	`409`	A withdrawal idempotency key was reused for a different intent
`SECRET_ROTATION_IN_PROGRESS`	`409`	A webhook secret was rotated again during the overlap window
`ACCOUNT_WITHDRAWAL_LIMIT_EXCEEDED`	`422`	The withdrawal total exceeds your account policy
`UNPROCESSABLE_ENTITY`	`422`	Valid JSON that cannot be processed, such as a rejected webhook URL
`RATE_LIMITED`	`429`	Too many requests for this key
`SERVICE_UNAVAILABLE`, `SIGNING_VERIFICATION_UNAVAILABLE`, `PARTNER_WEBHOOKS_DISABLED`	`503`	Temporarily unavailable; retry with backoff
`INTERNAL_SERVER_ERROR`, `BAD_GATEWAY`	`500`, `502`	Unexpected failure; retry with bounded backoff

Withdrawal-specific codes such as UNSUPPORTED_WITHDRAWAL_ROUTE are described on Single withdrawals.

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
`415`	Missing or wrong `Content-Type`	Send `Content-Type: application/json` on JSON writes
`422`	Valid JSON that cannot be processed	Correct the business input, or reduce the amount for a withdrawal limit
`429`	Too many requests	Back off and retry later
`500`, `502`	Unexpected server failure	Retry with bounded backoff and alert if it persists
`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 a withdrawal idempotency conflict, read the existing transaction or create a new intent; for a replayed nonce, retry with a new nonce
`422`	No	Correct the request’s business input, or wait and reduce the amount for a withdrawal limit
`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

Error Codes

Common Status Codes

Retry Guidance

Required Headers

​Error Codes

​Common Status Codes

​Retry Guidance

​Required Headers

Error Codes

Common Status Codes

Retry Guidance

Required Headers