Errors & status codes

Errors use conventional HTTP status codes and a consistent JSON body with a machine-readable code.

422 Unprocessable Entity

{
  "error": {
    "type": "compliance_error",
    "code": "holder_not_verified",
    "message": "The holder has not completed KYB.",
    "param": "holder.kyb_id",
    "request_id": "req_8sK2"
  }
}

HTTP	type	Example codes
400	invalid_request	parameter_missing, invalid_currency, amount_too_small
401	authentication_error	invalid_key, expired_token
403	permission_error	scope_missing, product_not_enabled
404	not_found	resource_missing
409	conflict	idempotency_mismatch, account_closed
422	compliance_error	holder_not_verified, restricted_industry, wallet_not_whitelisted
429	rate_limit	too_many_requests (Retry-After header)
5xx	api_error	upstream_unavailable

Handling errors

Retry 429 after the number of seconds in Retry-After, and 5xx with exponential backoff. Always reuse the same Idempotency-Key when retrying a POST.
Do not retry 4xx errors other than 429 without changing the request.
Include request_id when contacting support.