Errors

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"
}
FieldMeaningUse it to
error.codeThe kind of error, such as VALIDATION_ERROR or SERVICE_ERRORDecide whether to fix the request or retry
error.messageA general descriptionLog it
error.context.details[].codeThe specific reasonDecide what to do; this is the code your logic should branch on
error.context.details[].messageThe reason in wordsShow it to the user where appropriate
error.context.details[].fieldThe field at fault, when there is oneHighlight the field in your form
errorId, traceIdIdentifiers for this error and requestGive 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

StatusMeaningWhat to do
400The request is wrongFix the cause named in the error. Do not retry unchanged
401The MID header or the credentials are missing or wrongSee Authentication & Headers
429Too many requestsWait, then retry: 1 second, then 2, then 4
500Something went wrong on our sideRetry 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.