Troubleshooting

Error reference

A failed request returns a 4xx or 5xx status and a JSON body that says what went wrong.

Error format

422 Unprocessable content

{
  "error": {
    "type": "invalid_request",
    "message": "unitPriceMinor must contain digits only.",
    "code": "invalid_amount",
    "param": "lineItems[0].unitPriceMinor"
  }
}

type and message are always present. code gives a more specific reason where there is one, and param names the field at fault. Base your error handling on type and code. The message is written for people and its wording can change.

Status codes

Status	What happened	What to do
`400`	The request is malformed, for example the JSON doesn’t parse.	Fix the request. Retrying it unchanged won’t help.
`401`	The key is missing, invalid, revoked or expired.	Check the key, and that it matches the environment.
`404`	The resource doesn’t exist, or belongs to another workspace.	Check the id and which key you’re using.
`409`	An idempotency key was reused with a different body, or the document’s status doesn’t allow the action.	Use a new key, or fetch the document and check its status.
`422`	The request is well formed but a field fails validation.	Read `param` and correct that field.
`429`	You’ve sent too many requests.	Wait the number of seconds in `Retry-After`, then retry.
`5xx`	Something failed on our side.	Retry with backoff, using the same `Idempotency-Key`.