Errors
The shape of an error, what each status means, and when to retry.
The API answers with standard HTTP status codes: 2xx succeeded, 4xx means the request needs to change, 5xx means something failed on our side.
The error body
Every error has the same JSON shape:
JSON
{
"name": "BadRequest",
"message": "Validation error; `data` holds the message for each invalid field",
"code": 400,
"className": "bad-request",
"data": {
"recipient": { "phone": "Invalid phone number" }
}
}coderepeats the HTTP status andnamenames it.messageis meant for you, not for your customers.data, on a validation error, holds a message per invalid field, nested like the body you sent.
Status codes
| Status | Name | What to do |
|---|---|---|
400 | BadRequest | Fix the fields listed in data and send again. |
401 | NotAuthenticated | Log in again: the token is missing, expired or malformed. |
403 | Forbidden | The user may not do this on this account. |
404 | NotFound | The object does not exist, or belongs to an account you are not a member of. |
409 | Conflict | The object changed while you were changing it. Read it again, then retry. |
429 | TooManyRequests | Slow down and retry later. |
5xx | Retry later with a growing delay. |
Retrying safely
Retry only 409, 429 and 5xx, and wait longer after each attempt (for example 1, 2, 4 and 8 seconds). Before you retry a request that buys something, such as POST /shipments/labels, read the shipment first: if the first attempt went through, it already has a label.
Contacting support
Error answers carry a wsy-request-id header. Include it when you contact support about a failed request; it lets us find that exact call.