Error Codes
Every failure uses the standard error envelope — { "success": false, "error": { "code", "message" } }. Branch on error.code (a stable machine-readable slug), never on error.message (human-readable, may change between releases).
These are the common codes shared across endpoints. Endpoint-specific errors are also listed on each reference page; cashout has its own Cashout Errors table.
note
Transaction inquiry is the exception to the envelope above: its verdicts — including rejections like wrong_recipient — return 200 OK with a resultCode in data, not an error envelope. Only transport and auth failures there use the codes below. See its result codes.
| HTTP status | Error code | Meaning | How to fix |
|---|---|---|---|
| 400 | bad_request | Malformed request. | Send well-formed JSON to the correct method and path. |
| 401 | auth_api_key_invalid | API key missing, unknown, or gateway not verified. | Send a valid X-Api-Key; confirm the gateway is verified. |
| 401 | unauthorized | Authentication failed. | Check the credentials on the request. |
| 403 | forbidden | Authenticated but not allowed. | Ensure the key has permission and (for IP-gated endpoints) your server IP is allowlisted. |
| 404 | not_found | Resource does not exist or belongs to another gateway. | Check the ID — it must belong to your gateway. |
| 409 | conflict | The request conflicts with the resource's current state. | Re-read the resource; the operation is not valid in its current state. |
| 422 | validation_error | A field failed validation (missing required field, unknown currency code, …). | Fix the named field — check required, type, and mode-specific rules. |
| 429 | rate_limit_exceeded | Too many requests from your IP on this endpoint. | Honor the Retry-After header before retrying — see Rate Limits. |
| 500 | internal_error | Something failed on our side. | Safe to retry with exponential backoff. |
| 503 | service_unavailable | Temporarily unavailable. | Retry with exponential backoff. |