Skip to content

Errors

An error has an HTTP status in the 4xx or 5xx range and an RFC 9457 body, with the application/problem+json content type:

{
"type": "<the code's documentation URL>",
"title": "<summary of the error>",
"status": 409,
"code": "<stable code>",
"detail": "<the reason, for this case>",
"request_id": "req_01jcq4m5x2v7k9t3r8n6p0w1yz"
}
Field Content
type The documentation URL describing the code: this guide, at the code's anchor (.../guides/errors/#<code>).
title A short summary of the error, in English.
status The HTTP status, repeated in the body.
code The error's stable code. It does not change in v1.
detail The explanation for this case, in English.
errors Validation only: the errors, per field.
request_id The request's id (req_...), the same as in the X-Request-Id header.

Branch on code (and status), never on title or detail: texts can be reworded, codes cannot.

Every API response, successful or not, carries the X-Request-Id header (req_ followed by a ULID); an error repeats it in the body, as request_id. The same id is kept with the call in the call history and shows on the app's Calls tab, in the partner portal.

Keep it in your logs beside any error and quote it when you ask support for help: that is how we find that exact request.

Status When
400 The request cannot be processed as sent; for example, Idempotency-Key is missing on a write that requires it (idempotency).
401 The token is missing, wrong, expired or revoked, or the app's installation is not live (not installed yet, uninstalled, or the app suspended).
403 The token lacks the scope the endpoint needs (insufficient_scope).
404 The resource does not exist in the request's organization.
409 The resource's state refuses the action (for example, a shipment that can no longer be cancelled), or a request with the same idempotency key is still running.
422 Validation failed (errors per field), the action's rules refuse it, or the same idempotency key came with another body.
429 The rate limit was exceeded; retry after Retry-After (rate limits).

A write through the API runs the same action as the button in the dashboard, with the same checks. When the action refuses (the order cannot get another shipment, the invoice already exists), the response is a 409 or 422, with the reason in detail and a stable code for that case.

Every code the API returns, with its status. An error's type links to its row here.

Code Status Meaning
bad_request 400 The request cannot be processed as sent.
unauthenticated 401 The token is missing, wrong, expired or revoked, or the app's installation is not live (not installed yet, uninstalled, or the app suspended).
insufficient_scope 403 The token lacks the scope the endpoint needs (the installation was not granted it, or a private app's token was asked with a scope leaving it out); detail names it.
forbidden 403 The request is not allowed for this caller.
not_found 404 The resource or path does not exist in the request's organization.
method_not_allowed 405 The path exists, but not with this HTTP method.
payload_too_large 413 The body is larger than the API accepts.
validation_failed 422 One or more fields are invalid; errors lists them per field.
idempotency_key_required 400 The write requires an Idempotency-Key header and it is missing.
idempotency_key_invalid 400 The Idempotency-Key value is not accepted: 1 to 255 visible ASCII characters, without spaces.
idempotency_key_reused 422 The same Idempotency-Key was already used with another request.
idempotency_in_progress 409 A request with the same Idempotency-Key is still running; retry after a pause.
conflict 409 The resource's state refuses the request.
rate_limited 429 Too many requests; retry after Retry-After seconds.
server_error 500 An error on our side; retry later with the same Idempotency-Key.
unavailable 503 The API is temporarily unavailable; retry later.
Code Status Meaning
order_inactive 409 The order is no longer active in its store.
order_has_shipment 409 The order already has a shipment (asked, issued or with an unknown outcome).
order_not_ready 409 The order is not ready: a blocking issue, no delivery service chosen, or prices still being fetched.
try_again_later 409 The courier is unreachable or throttling, or the order kept changing; retry later.
shipment_refused 422 The service is off, the order does not fit the courier's terms, or the courier refused it.
shipment_not_cancellable 409 Only a shipment in status created can be cancelled.
cancel_at_courier 409 An AWB entered by hand that the courier cannot be asked about: cancel it at the courier.
courier_unavailable 409 The courier account cannot be reached now; retry later.
cancel_refused 409 The courier refused the cancellation, or the call to it failed.

order_inactive is shared with shipments.

Code Status Meaning
order_already_invoiced 409 The order already has an invoice, asked or issued.
order_blocked 409 One of the order's issues blocks invoicing.
invoicer_unavailable 409 The invoicing account is paused or waiting to reconnect; retry later.
invoice_refused 422 No invoicing account for the order's store, an account that cannot issue, or an order the invoicing software refuses.
Code Status Meaning
not_a_store 403 The caller is not a store app installed as a store in this organization (store apps).
integration_paused 409 The store is paused or held in this organization; send again once it resumes.
order_in_progress 409 Another send of the same order is still being taken in (store apps); send it again.
  • 4xx: fix the request before sending it again. Exceptions: 429, retried after Retry-After, and 409 for an idempotency key still running, retried after a pause.
  • 5xx or a network error: retry after a pause that grows with every attempt. On writes, send the same Idempotency-Key, so the operation never runs twice.

The same request, unchanged and under the same Idempotency-Key, may succeed later after one of these codes: the answer is not kept under the key, so a retry runs again (idempotency).

Code When it may pass
validation_failed Once the data it names exists, for example an order_id not synced yet.
rate_limited After Retry-After.
idempotency_in_progress Once the first request with the key ends.
server_error, unavailable Later.
order_not_ready Once the order is ready: its blocking issue fixed, a delivery service chosen, its prices in.
try_again_later, courier_unavailable Once the courier answers again.
cancel_refused When the call to the courier failed; a courier's own refusal stays.
order_blocked Once the order's blocking issue is fixed.
invoicer_unavailable Once the invoicing account is back.
integration_paused Once the store resumes in the organization.
order_in_progress Once the other send of the order ends, a moment later.

Every other 4xx is definitive: the same key returns the same answer for 24 hours.