Integration

Handling errors

What a failure looks like, and which failures are worth retrying.

Every error on this surface has the same shape, and it is worth reading once:

{
  "statusCode": 400,
  "errorCode": "malformed_request",
  "message": "Invalid value for: query parameter merchantId (missing)",
  "tracer": "610ad7c6-ddf9-4364-9e9d-cfdb087d5a85",
  "detail": null,
  "errorTypeDescription": "The server is unable to process the request due to client error.",
  "metadata": null
}

Branch on errorCode, never on message. The code is a closed vocabulary; the message is prose written for a person and it will change without warning.

Keep the tracer. It is the only handle on a specific failure inside the platform, when you ask us what went wrong, it is the difference between an answer in minutes and an answer in days. Log it with every non-2xx.

What to retry. A 409 means you have already done this, read the resource rather than sending it again. A 422 means the platform understood you and refused; retrying identical input will be refused identically. A 429 or 503 is worth retrying with backoff. A 400 is a bug in your request and no amount of retrying fixes it.

And an HTTP 200 is not a successful payment. The status code tells you the request was understood. Whether the money moved is in the resource's own status, which is why the payment guides tell you to read it.

See testing.