Skip to main content

​
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

StatusMeaningTypical codes
200 / 201Success—
400Bad request — fix the request and retryvalidation_error, bad_request
401Authentication failedunauthorized, invalid_signature, jwt_expired
403Authenticated but not allowedforbidden, ip_not_allowed, account_suspended
404Resource not foundnot_found, quote_not_found
409State conflictquote_used, wallet_frozen
413Request body too large (>64 KB)bad_request
422Business rule rejection — retry will not helpsee below
429Rate limit hit; wait and retryrate_limited
500Our problem; safe to retry with backoffinternal_error

​
422 — business rule codes

These represent rules the request violated, not syntax errors.
CodeTrigger
insufficient_fundsWallet balance is too low to cover the transaction amount
per_payout_limit_exceededTransaction exceeds your per-transaction cap
daily_limit_exceededToday’s send volume would exceed your daily cap
monthly_limit_exceededThis month’s send volume would exceed your monthly cap
quote_expiredThe quote has expired
invalid_signatureQuote signature mismatch
rate_movedExchange rate moved more than 0.5% since the quote was issued
screening_failedRecipient failed sanctions screening

​
Retrying

StatusRetry?
5xx, 429Yes, with exponential backoff (start at 1s, max 60s)
401 jwt_expiredRe-login and retry once
All other 4xxNo — fix the request first
Use idempotency_key on sendPayoutRequest so a retry after a network error does not accidentally create a duplicate transaction.