Errors
Errors are JSON: { "error": { "code": "...", "message": "..." } }. Rely on code, not on message.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request |
The request is malformed or a field is invalid (the message names the field). |
| 400 | invalid_pdf |
label_pdf_base64 decodes to something that is not a PDF. |
| 401 | unauthorized |
Missing, invalid or revoked key. |
| 404 | not_found |
Unknown resource, a resource of another account, an endpoint that does not exist, or live orders not yet enabled for you. |
| 404 | snapshot_not_available |
GET /v1/catalog/full (and its download) before the first snapshot exists: use /catalog/changes meanwhile. |
| 409 | idempotency_conflict |
Same Idempotency-Key with a different body. |
| 409 | request_in_progress |
The same key is still being processed (retry later with the same key, never a new one), or GET /v1/orders/{order_id} for an order whose creation is still being processed. |
| 409 | already_shipped |
The parcel is already shipped (AWB replacement) or the sandbox order is already shipped. |
| 413 | payload_too_large |
Request body over 256 KB (4 MB for the AWB upload; the PDF itself 2 MB). |
| 422 | insufficient_deposit |
The accepted lines plus the flat shipping fee, if any, exceed your available balance. |
| 422 | destination_not_allowed |
ship_to.country is not in your allowed_countries, or a GB order has no zip or a Northern Ireland (BT) zip. |
| 429 | rate_limited |
Rate limit; wait for the Retry-After header. |
| 500 | internal_error |
Temporary: retry with exponential backoff (the same applies to any other 5xx). |
Line-level rejections inside a 201 response use reason, not an HTTP error: out_of_stock, unknown_sku, price_changed, duplicate_line,
not_created. See Orders.