Errors

Every error has the same shape:

JSON

{
  "statusCode": 422,
  "code": "ASSET_NOT_ACCEPTED",
  "message": "Human-readable description",
  "error": "ASSET_NOT_ACCEPTED"
}

Branch on code — it is stable. message is for people and may be reworded at any time; never parse it. error is kept for older clients and holds whatever that error has always carried; never branch on it either. Some errors add fields (blockers, reasons, networks).

Status	`code`	Meaning
`400`	`VALIDATION_ERROR`	Invalid body, parameters or headers (for example a missing `Idempotency-Key`)
`400`	`IDEMPOTENCY_KEY_TOO_LONG`	The `Idempotency-Key` is longer than 255 characters — nothing was created; send a shorter key
`400`	`INVALID_INPUT`	A value in the wrong format — for example an id in the path that is not a UUID
`400`	`BTC_XPUB_MISSING`	A Bitcoin invoice needs your Bitcoin account key
`400`	`ASSET_NOT_FOUND`	With the deprecated `amountRaw`: that asset is not enabled on the network you named (with `amountDecimal` the same mistake is `VALIDATION_ERROR`) — `GET /chains/{chainId}/assets` lists what is
`401`	`UNAUTHORIZED`	Missing, invalid or revoked API key
`402`	`PAYMENT_REQUIRED`	Over your plan's capacity, or at its customer limit — top up or upgrade
`403`	`ACCOUNT_DEACTIVATED` / `ACCOUNT_NOT_ACTIVE`	The account behind this valid key is deactivated or suspended — sign in to the dashboard, or contact support
`403`	`INSUFFICIENT_SCOPE`	The key is valid but lacks a scope this route needs
`403`	`EMAIL_NOT_VERIFIED`	Confirm your email address first
`404`	`NOT_FOUND`	Not found, or it belongs to another account
`409`	`IDEMPOTENCY_KEY_REUSED`	This `Idempotency-Key` was used with a different body, or on another endpoint — use a new key
`409`	`IDEMPOTENCY_KEY_IN_PROGRESS`	A request with this key is still being processed — retry after `Retry-After` seconds to receive its result
`409`	`CUSTOMER_EXTERNAL_REF_TAKEN`	A customer with this `external_ref` already exists — fetch it with `GET /customers?external_ref=…`, or use another reference
`409`	`CUSTOMER_ARCHIVED`	That `external_ref` belongs to a customer you deleted — use a new reference
`409`	`ACCOUNT_RESOURCE_LIMIT_REACHED`	Your plan's limit for this resource (webhooks, API keys, buttons, subscriptions, customer addresses) is reached
`422`	e.g. `ASSET_NOT_ACCEPTED`, `CHAIN_NOT_IN_PLAN`, `ENVIRONMENT_MISMATCH`, `XRPL_DEPOSIT_UNAVAILABLE`	A business rule refused the request; `message` says what to do
`429`	`TOO_MANY_REQUESTS`	Too many requests — wait the `Retry-After` header's seconds. Never a `401`: your key is fine
`500`	`INTERNAL_ERROR`	Unexpected server error — always the generic "An unexpected error occurred"
`503`	e.g. `DETECTION_UNAVAILABLE`, `AUTH_UNAVAILABLE`, `ACCOUNT_RESOURCE_BUSY`	We cannot safely do this right now — retry shortly. Never rotate a key because of a `503`