How an error response is shaped, and what to do with it.
An error response carries a general error.code, and the specific reason inside error.context.details. This example is from Create Order:
{
"status": "failure",
"error": {
"message": "Transfer Creation failed",
"code": "VALIDATION_ERROR",
"context": {
"details": [
{ "code": "STANDARD_KYC_REQUIRED", "message": "Limit breached – Standard KYC is required." }
]
}
},
"errorId": "255b13da-1a62-49f6-a948-17742c20c261",
"traceId": "69ec39b5-e36f-4fe2-83cb-b8766d1afc15"
}| Field | Meaning | Use it to |
|---|---|---|
error.code | The kind of error, such as VALIDATION_ERROR or SERVICE_ERROR | Decide whether to fix the request or retry |
error.message | A general description | Log it |
error.context.details[].code | The specific reason | Decide what to do; this is the code your logic should branch on |
error.context.details[].message | The reason in words | Show it to the user where appropriate |
error.context.details[].field | The field at fault, when there is one | Highlight the field in your form |
errorId, traceId | Identifiers for this error and request | Give them to support |
An order that is accepted and fails later carries failureCode and failureMessage on the order and on its webhook instead. Those are on Orders & Statuses.
The same on every endpoint
| Status | Meaning | What to do |
|---|---|---|
400 | The request is wrong | Fix the cause named in the error. Do not retry unchanged |
401 | The MID header or the credentials are missing or wrong | See Authentication & Headers |
429 | Too many requests | Wait, then retry: 1 second, then 2, then 4 |
500 | Something went wrong on our side | Retry once. If it fails again, contact support with the traceId |
Each endpoint page says what to do for every response it returns. The full catalog of codes is on the Errors page in the guides.