Errors

Error envelope

{
  "ok": false,
  "request_id": "8c1f4b2a-9d3e-4a71-b6c8-5e2f0a7d1934",
  "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`

Payout error codes

Returned by sendPayoutRequest and getPayoutStatus.

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

404 — no_route

The country, currency and payment method combination is not enabled on your account. Contact support to have the corridor added.

Payin error codes

Returned by the two gateway payment endpoints.

422 — business rule codes

Code	Trigger
`redirect_domain_not_allowed`	Your `success_url` or `fail_url` host is not on your allowed domains
`amount_below_minimum`	The amount is below the minimum set for your account

409 — state conflicts

Code	Trigger
`wallet_frozen`	Your wallet is frozen, so a payment cannot be opened
`not_payable`	The payment has already settled or was closed
`expired`	The payment window passed before a method was chosen

503 — pricing_unavailable

Fees could not be quoted just now. Retry shortly; nothing was created.

A payment reference that belongs to another merchant returns not_found, exactly as one that never existed does. The endpoint never confirms that someone else’s order exists.

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

Payins

Payouts

Sandbox testing

Go to production

Errors

Error envelope

HTTP status codes

Payout error codes

422 — business rule codes

404 — no_route

Payin error codes

422 — business rule codes

409 — state conflicts

503 — pricing_unavailable

Retrying

​Error envelope

​HTTP status codes

​Payout error codes

​422 — business rule codes

​404 — no_route

​Payin error codes

​422 — business rule codes

​409 — state conflicts

​503 — pricing_unavailable

​Retrying

Error envelope

HTTP status codes

Payout error codes

422 — business rule codes

404 — no_route

Payin error codes

422 — business rule codes

409 — state conflicts

503 — pricing_unavailable

Retrying