Errors

Error envelope

{
  "ok": false,
  "request_id": "01J9F5Z4X7Y3K2B1Q0M8N7V6T5",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}

request_id — include this when contacting support
error.code — machine-readable; safe to switch on
error.message — human-readable; do not parse

HTTP status codes

Status	Meaning	Typical codes
`200` / `201`	Success	—
`400`	Bad request — fix the request and retry	`validation_error`, `bad_request`
`401`	Authentication failed	`unauthorized`, `jwt_expired`
`403`	Authenticated but not allowed	`forbidden`, `account_suspended`
`404`	Resource not found	`not_found`, `no_route`
`409`	State conflict	`wallet_frozen`
`413`	Request body too large (>64 KB)	`bad_request`
`422`	Business rule rejection — retry will not help	see below
`429`	Rate limit hit; wait and retry	`rate_limited`
`500`	Our problem; safe to retry with backoff	`internal_error`

422 — business rule codes

These represent rules the request violated, not syntax errors.

Code	Trigger
`insufficient_funds`	Wallet balance is too low to cover the transaction amount
`daily_limit_exceeded`	Today’s send volume would exceed your daily cap
`monthly_limit_exceeded`	This month’s send volume would exceed your monthly cap
`fee_exceeds_amount`	The fee exceeds the send amount — try a larger amount
`rate_moved`	Exchange rate moved more than 0.5% since the quote was issued — retry
`screening_failed`	Recipient failed sanctions screening

Retrying

Status	Retry?
`5xx`, `429`	Yes, with exponential backoff (start at 1s, max 60s)
`401 jwt_expired`	Re-login and retry once
All other `4xx`	No — fix the request first

Use idempotency_key on sendPayoutRequest so a retry after a network error does not accidentally create a duplicate transaction.

Get started

Core concepts

Go to production

Error envelope

HTTP status codes

422 — business rule codes

Retrying

​Error envelope

​HTTP status codes

​422 — business rule codes

​Retrying

Error envelope

HTTP status codes

422 — business rule codes

Retrying