Errors

Every error response has the same shape:

{ "success": false, "error": "This order can no longer be changed or cancelled here. Refresh the page to see its latest status.", "code": "order_not_editable" }

• code is stable and machine-readable. Your program should branch on it.
• error is an English message for people. It may change.
• details (on validation_failed only) lists each problem with the field path and a message.
• The X-Request-Id header identifies the request. Quote it when you contact support.

How requests are checked

A path that doesn't exist (404 not_found) or a wrong method (405 method_not_allowed) is answered first. Then the checks run in this order, and the first that fails decides the error:

1. The API key: 401 invalid_api_key, 403 api_not_enabled, 403 account_action_required. Too many failed attempts from one network are answered 429 rate_limited at this step.
2. The rate limit: 429 rate_limited. This comes before the permission check, so refused calls still count.
3. The key's permission: 403 insufficient_scope.
4. For writes, whether your account is on hold: 403 account_on_hold.
5. The id in the path, if it isn't a valid id: 404 not_found.
6. The query string and the body: 400 invalid_json, 413 payload_too_large, 415 unsupported_media_type, 422 validation_failed.
7. The Idempotency-Key: 400, 409 request_in_progress, 422 idempotency_key_reused. Errors in the steps above never use up a key.
8. The business rules: a specific code with 404, 409 or 422. An id in the path that is valid but doesn't exist or isn't yours returns 404 not_found on reads, and the endpoint's own code (such as 404 order_not_found) on writes; each endpoint lists its codes.

General error codes

Business rule codes

Business rules return their own codes. Their status follows fixed rules:

• codes ending in _not_found are 404: something in the path doesn't exist or isn't yours;
• codes ending in _changed are 409: the data changed since you read it; read it again and decide again;
• other state conflicts, such as order_not_editable or shipment_not_cancellable, and uniqueness conflicts, such as store_order_no_taken and library_sku_taken, are 409;
• quota and usage limits are 409 as well, because waiting doesn't reliably clear them; don't retry them automatically;
• everything else is 422. An id inside the request body (a product, a shipping option) that doesn't exist or isn't yours is a 422 rule failure, not a 404;
• a rule failure we can't describe more precisely is 422 request_rejected.

The codes each endpoint can return are listed in its reference section. All business codes the API returns today:

The message column shows the current English text; it may change.

Handling errors