Errors

Error response

Failed requests use the same envelope as successful ones. status is "error" and message is a machine-readable error code you can branch on. data adds detail where it helps, often a readable message you can show or log.

{
  "status": "error",
  "message": "RECIPIENT_INACTIVE",
  "data": { "message": "This recipient is inactive. Reactivate it to send money." }
}

Validation errors

When the body or query fails validation, data maps each invalid field (as a dotted path) to the first problem found with it:

{
  "status": "error",
  "message": "VALIDATION_ERROR",
  "data": {
    "currency": "String must contain exactly 3 character(s)",
    "destination.accountNumber": "Account number is required"
  }
}

HTTP status codes

Common error codes

Each endpoint page lists the errors specific to it.

Retry guidance

• Do not retry 4xx errors unchanged. Fix the request first. The exception is 429: wait for Retry-After, then retry.
• Retry 500 and 503 with exponential backoff for reads, and for POST /collections and POST /payouts sent with an Idempotency-Key.
• Never retry a payout sent without an Idempotency-Key until you have checked GET /payouts. A timeout does not mean it failed, and you may pay twice.
• Log the full response body (status, message and data) of every failed call; include it when you contact support.