#Errors

Every error, on every endpoint, is the same JSON shape. There is no second format to handle.

#The envelope

{
  "error": "insufficient_balance",
  "message": "optional human-readable detail",
  "details": [{ "path": "amount", "message": "Invalid" }]
}

error is the contract. message is a courtesy. Code that switches on message text will break the first time someone improves the wording.

#What each status class means for a retry

The status code answers one question — should I send this again? — and the answer is different for each class.

400 — the request is wrong. Body or query failed validation, or a domain rule was violated: validation_error, unknown_asset, asset_disabled, invalid_amount, bad_amount, invalid_address, invalid_pair, no_route; on withdrawals also amount_below_minimum (a zero or negative amount — payouts have no other floor), self_transfer (the recipient is the user's own deposit address — nothing would move but the network fee) and invalid_request. Never retry unchanged. Nothing was created and nothing was charged. Fix the request, or surface the problem to whoever typed it. On validation_error, details[] names the exact field.

401 unauthorized — the key is missing, malformed or unknown. Never retry; no amount of backoff produces a valid key. See Authentication.

403 — the key is real, but your account, your login or the feature may not do this. email_unverified (the owner login has not verified its email), account_paused (an operator hold) and account_suspended answer every call on the key until the state changes — see Authentication. session_required and forbidden_role mean the action exists only on the dashboard, with a second factor and the right role; own_account_only is a dashboard session trying to move a customer's balance, which only your integration may do. None of these is a bug in your request, and retrying does not help; the change that lifts them is ours, and the dashboard shows the state.

400 unknown_asset — an asset id we do not support. Take ids from GET /v1/assets.

404 — not found, or not yours. An unknown id and another merchant's id are deliberately indistinguishable, so you cannot enumerate anyone else's records. Also returned by the idempotency-key lookups when no record was created for that key — which is a meaningful answer there, not an error. See Idempotency.

409 — a conflict with existing state. The request was well-formed but the world disagreed: insufficient_balance, idempotency_conflict, card_state, kyc_not_approved, provider_rejected, not_cancellable, too_many_endpoints, no_own_account (your own balance has not been opened yet) and not_pending (a parked payout someone already decided). Do not blind-retry. Read the current state, decide, and act — most of these change only when something else changes first (a deposit lands, KYC is approved, a card is unfrozen).

Two card errors are retired (20 September 2026) and will never be raised again: 409 card_close_underfunded (a card had to hold the issuer's cancellation charge before it could be closed) and 409 card_refund_wallet_empty (a close waited on the wallet that pays refunds). A close is now always accepted, and where the money is reads as close_refund.state on GET /v1/cards/{id}. Delete any handling of the two codes.

409 provider_rejected is worth calling out: it is a definitive failure. The provider looked and refused, and any charge is already reversed. details.order_id names the order.

500 internal_error — something broke on our side. The body carries no message. Safe to retry with backoff and the same idempotency key; whether the operation landed is indeterminate, so resolve it with the key lookup rather than assuming either way.

503 — a dependency is unavailable, and your request was fine. chain_unavailable (no adapter configured for that asset's chain), cards_disabled, swap_disabled, swap_unavailable, exchange_error. Retry later, unchanged. Do not adjust the request to work around it, and do not queue a modified version of it on your side.

#Retry decision table

The one rule that never bends: when you retry a mutation, reuse the original idempotency_key. A fresh key on a retry is how a customer gets paid twice.

The same instinct applies everywhere: before you refund, re-charge, or tell a customer something final, reconcile against the resource read. Webhooks are hints; the poll is truth.

#Catalogue

Generated from the components.responses block of the OpenAPI contract (v1.0.0) — this is every named error response and the error codes it can carry.

#Debugging an integration

GET /v1/developer/logs returns the method, route, status and duration of your recent calls, kept for 14 days, with no bodies and no query strings. When a call seems to have vanished, check there first: it tells you whether the request reached the platform at all, and what status it left with.

#Daily limits

Calls that cost a third party money per request are capped per account per day: starting a new identity verification (POST /v1/kyc/start, resuming one is free) and uploading card KYC documents (POST /v1/cards/kyc/upload). Past the cap the answer is 429 daily_limit_reached until the next UTC day. If your volume genuinely needs more, ask us to raise it.