Support
Getting started

Errors

The API uses conventional HTTP status codes and returns a consistent JSON error body you can branch on programmatically.

Error format

Response · 400 Bad Request
{
  "error": {
    "type": "validation_error",
    "code": "invalid_currency",
    "message": "destination_currency 'XYZ' is not supported.",
    "param": "destination_currency",
    "request_id": "req_5f1e8d7c"
  }
}

Always log the request_id — support can trace any request with it.

HTTP status codes

CodeMeaning
200Success.
201Resource created (transfers, payouts, cards).
400Invalid request — check error.param and error.message.
401Missing or invalid API key.
403Key is valid but not permitted for this resource (restricted key or IP not allowlisted).
404Resource does not exist in this environment.
409Conflict — usually a state issue, e.g. executing an expired quote.
422Request is well-formed but cannot be processed, e.g. insufficient balance.
429Rate limit exceeded — respect the Retry-After header.
500Something failed on our side. Safe to retry with the same idempotency key.

Common error codes

error.codeDescription
invalid_api_keyThe key is malformed, revoked or for the wrong environment.
insufficient_balanceYour wallet balance cannot cover the transaction plus fees.
quote_expiredThe FX quote lapsed before the transfer was created. Request a new quote.
invalid_beneficiaryAccount resolution failed for the destination account.
duplicate_transactionAn identical request was blocked. Use idempotency keys for intentional retries.
compliance_holdThe transaction requires manual review. You will receive a webhook when it clears.
rate_limitedToo many requests. Default limit is 100 requests per minute per key.

Handling failures