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"}Fields
Section titled "Fields"| 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.
The request id
Section titled "The request id"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.
Statuses
Section titled "Statuses"| 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). |
Refused actions
Section titled "Refused actions"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.
Any endpoint
Section titled "Any endpoint"| 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. |
Shipments
Section titled "Shipments"| 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. |
Invoices
Section titled "Invoices"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. |
Store apps
Section titled "Store apps"| 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. |
What to do
Section titled "What to do"4xx: fix the request before sending it again. Exceptions:429, retried afterRetry-After, and409for an idempotency key still running, retried after a pause.5xxor a network error: retry after a pause that grows with every attempt. On writes, send the sameIdempotency-Key, so the operation never runs twice.
Codes that may pass later
Section titled "Codes that may pass later"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.