Errors

Every error response is JSON in this shape:

json

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "insufficient balance: requested 5000000, available 3000000",
    "request_id": "8c3a..."
  }
}

Status codes

HTTP	Code	Meaning
400	`INVALID_INPUT`	Field validation failed; check the message.
400	`IDEMPOTENCY_REQUIRED`	Missing `Idempotency-Key` on a write.
400	`INSUFFICIENT_BALANCE`	Payout / refund exceeds available.
400	`INVALID_DESTINATION`	Address format invalid for the chain.
400	`REFUND_EXCEEDS_NET`	Refund larger than what's left to refund.
400	`MEMO_NOT_ALLOWED`	Memo on a network that doesn't use one.
400	`PAY_IN_ASSET_NOT_ALLOWED`	Asset/network combo not enabled for you.
401	`MISSING_API_KEY`	No `Authorization` header.
401	`INVALID_API_KEY`	Key not recognised or mismatched.
401	`API_KEY_REVOKED`	Key revoked.
403	`MISSING_SCOPE`	Key doesn't have the required scope.
403	`IP_NOT_ALLOWED`	Request IP outside the key's allowlist.
403	`MERCHANT_SUSPENDED`	Merchant account is suspended.
403	`MERCHANT_BANNED`	Merchant account is banned.
403	`DAILY_CAP_EXCEEDED`	Payout cap for the asset reached.
404	`INVOICE_NOT_FOUND` / `PAYOUT_NOT_FOUND` / `REFUND_NOT_FOUND`	Resource doesn't exist (or isn't yours).
409	`INVOICE_NOT_CANCELLABLE`	Only awaiting_deposit invoices can be cancelled.
409	`INVOICE_NOT_REFUNDABLE`	Invoice must be paid first.
409	`DUPLICATE`	Idempotency-Key replay with a different body, or duplicate `order_id`.
429	`RATE_LIMIT`	Too many requests on this key.
429	`API_KEY_LOCKED`	Brute-force lockout in effect.
503	`POOL_EXHAUSTED`	No deposit address available; retry shortly.
503	`PAYOUTS_DISABLED` / `REFUNDS_DISABLED` / `MERCHANT_DISABLED`	Operator paused that surface; try later.

Retry strategy

Treat 429 and 503 as transient. Use the Retry-After header when present. 5xx responses can be retried with the same Idempotency-Key — we return the cached response if the original write completed. 4xx other than 409 should be treated as final and not retried.