How errors look

When a request works, you get a 2xx status code. When it doesn’t, you get a 4xx or 5xx code and an error object that explains what went wrong.

The error object

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Request validation failed",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "source_amount", "message": "source_amount must be a positive decimal string" }
    ]
  }
}

Field	What it means	Always there?
`type`	The group the error belongs to, for example `validation_error`. Use it for broad handling.	Yes
`code`	The exact error, for example `quote_expired`. Use it for specific handling.	Yes
`message`	A sentence a person can read. It may change, so don’t write code that depends on it.	Yes
`request_id`	The ID of your request. Send it to support if you need help.	Yes
`status`	The HTTP status code, repeated here for convenience.	Yes
`errors`	For field problems: a list of each `field` and its `message`. Nested fields use dots, for example `payment_details.details.address`.	Only for field problems
`param`	The single field the error is about.	Sometimes

Some errors add extra fields to help you, such as requested_version and supported_versions on version errors.

Idempotency errors are the one exception: they only have code and message.

How to handle errors

Check the status code

4xx means something about the request needs to change. 5xx means a problem on our side or with a partner, and trying again later may work. See Status codes.

Check the code

Handle the codes you expect, such as quote_expired. See Error codes.

Show or log the message

If it’s a field problem, read errors to see exactly which fields to fix.

Log the request ID

Always log request_id. Support can find your request with it.

Should I retry?

Status	Retry?
`400`, `401`, `403`, `404`, `409`, `413`, `422`	No. Fix the request first.
`429`	Yes, after the number of seconds in the `Retry-After` header.
`500`, `503`, `504`	Yes, after a short wait. Use the same `Idempotency-Key` so nothing is created twice.

Get started

Set up your account

Before you build

Core flows

Webhooks

Errors

The error object

How to handle errors

Should I retry?

​The error object

​How to handle errors

​Should I retry?

The error object

How to handle errors

Should I retry?