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
| Code | Meaning |
|---|---|
| 200 | Success. |
| 201 | Resource created (transfers, payouts, cards). |
| 400 | Invalid request — check error.param and error.message. |
| 401 | Missing or invalid API key. |
| 403 | Key is valid but not permitted for this resource (restricted key or IP not allowlisted). |
| 404 | Resource does not exist in this environment. |
| 409 | Conflict — usually a state issue, e.g. executing an expired quote. |
| 422 | Request is well-formed but cannot be processed, e.g. insufficient balance. |
| 429 | Rate limit exceeded — respect the Retry-After header. |
| 500 | Something failed on our side. Safe to retry with the same idempotency key. |
Common error codes
| error.code | Description |
|---|---|
| invalid_api_key | The key is malformed, revoked or for the wrong environment. |
| insufficient_balance | Your wallet balance cannot cover the transaction plus fees. |
| quote_expired | The FX quote lapsed before the transfer was created. Request a new quote. |
| invalid_beneficiary | Account resolution failed for the destination account. |
| duplicate_transaction | An identical request was blocked. Use idempotency keys for intentional retries. |
| compliance_hold | The transaction requires manual review. You will receive a webhook when it clears. |
| rate_limited | Too many requests. Default limit is 100 requests per minute per key. |
Handling failures
- Treat
4xxas permanent for that request — fix the input before retrying. - Treat
429and5xxas transient — retry with exponential backoff and the sameIdempotency-Key. - Money movement is asynchronous: a
201means accepted, not delivered. Track final state via webhooks.