Error codes

All error responses share one shape. Branch on code, not only the HTTP status.

{ "error": { "code": "invalid_request", "message": "..." } }

The short version

• 503 service_unavailable … Temporary. A Retry-After header is sent — follow it
• 503 capability_not_enabled … Not enabled in this environment; retrying will not help (no Retry-After)
• 429 … Retry per Retry-After
• 422 / 400 … The request is wrong; retrying as-is will not help
• 401 / 403 … Token or scope problem
• 404 … Not found. Also returned when you lack access (we do not reveal existence)

This page is generated from the API implementation (98 codes), so it cannot drift from the code.

Common

Code	HTTP	What to do
capability_not_enabled	503	Not enabled in this environment — retrying will not help. No Retry-After is sent; ask us about availability
internal_error	500	Our problem. Contact us if it reproduces
payload_too_large	413	Reduce the request body (limit: 1 MiB)
service_unavailable	503	Retry after a delay (a Retry-After header is sent)

Authentication

Code	HTTP	What to do
invalid_client	400 / 401	Fix the request. Retrying as-is will not help
invalid_grant	400	Fix the request. Retrying as-is will not help
invalid_request	400 / 422	Fix the request. Retrying as-is will not help
invalid_scope	400	Fix the request. Retrying as-is will not help
not_found	404	Not found (also returned when you lack access)
unsupported_grant_type	400	Fix the request. Retrying as-is will not help
unsupported_response_type	400	Fix the request. Retrying as-is will not help
unsupported_token_type	400	Fix the request. Retrying as-is will not help

Idempotency & rate limiting

Code	HTTP	What to do
idempotency_key_conflict	422	Fix the request. Retrying as-is will not help
idempotency_key_required	400	Fix the request. Retrying as-is will not help
idempotency_request_in_progress	409	Conflict. Re-fetch the current state
insufficient_scope	403	Insufficient permission. Check the required scope
invalid_token	401	Obtain a new token
rate_limited	429	Retry per Retry-After.
token_revoked	401	Obtain a new token
unauthorized	401	Obtain a new token

Catalog, categories, inventory

Code	HTTP	What to do
annotation_write_failed	500	Our problem. Contact us if it reproduces
axis_without_values	422	Fix the request. Retrying as-is will not help
bundle_not_allowed	400 / 422	Fix the request. Retrying as-is will not help
bundle_required	422	Fix the request. Retrying as-is will not help
cancel_by_after_event_start	422	Fix the request. Retrying as-is will not help
cancel_by_before_sell_from	422	Fix the request. Retrying as-is will not help
cancel_by_required	422	Fix the request. Retrying as-is will not help
category_depth_exceeded	422	Fix the request. Retrying as-is will not help
category_not_found	422	Fix the request. Retrying as-is will not help
component_has_variants	422	Fix the request. Retrying as-is will not help
component_not_found	422	Fix the request. Retrying as-is will not help
conflict_manual_override	409	Conflict. Re-fetch the current state
duplicate_axis	422	Fix the request. Retrying as-is will not help
duplicate_axis_value	422	Fix the request. Retrying as-is will not help
duplicate_image_id	422	Fix the request. Retrying as-is will not help
duplicate_variant_combination	409 / 422	Conflict. Re-fetch the current state
duplicate_variant_sku	409 / 422	Conflict. Re-fetch the current state
external_ref_conflict	409	Conflict. Re-fetch the current state
free_ticket_price_must_be_zero	422	Fix the request. Retrying as-is will not help
gift_must_not_ship	422	Fix the request. Retrying as-is will not help
hierarchy_move_not_allowed	400	Fix the request. Retrying as-is will not help
image_fetch_failed	422	Fix the request. Retrying as-is will not help
image_invalid	422	Fix the request. Retrying as-is will not help
image_not_found	422	Fix the request. Retrying as-is will not help
image_too_large	422	Fix the request. Retrying as-is will not help
image_url_not_allowed	422	Fix the request. Retrying as-is will not help
immutable_field	409	Conflict. Re-fetch the current state
immutable_variation_axes	400 / 409	Conflict. Re-fetch the current state
incomplete_image_order	422	Fix the request. Retrying as-is will not help
invalid_parameter	400	Fix the request. Retrying as-is will not help
invalid_sell_period	422	Fix the request. Retrying as-is will not help
invalid_ticket_valid_period	422	Fix the request. Retrying as-is will not help
inventory_busy	409	Nothing was written. The stock row was in use (e.g. a checkout in progress). Resend after Retry-After with the same Idempotency-Key, or try in the next cycle
inventory_not_updatable_here	400	Fix the request. Retrying as-is will not help
inventory_out_of_range	422	Fix the request. Retrying as-is will not help
lottery_date_before_sell_by	422	Fix the request. Retrying as-is will not help
lottery_not_allowed	422	Fix the request. Retrying as-is will not help
lottery_required	422	Fix the request. Retrying as-is will not help
managed_by_other	409	Conflict. Re-fetch the current state
negative_inventory	422	Fix the request. Retrying as-is will not help
no_image_cannot_activate	422	Fix the request. Retrying as-is will not help
no_variation_axes	422	Fix the request. Retrying as-is will not help
number_of_sets_out_of_range	422	Fix the request. Retrying as-is will not help
number_of_sets_required	422	Fix the request. Retrying as-is will not help
parent_category_not_found	422	Fix the request. Retrying as-is will not help
plan_limit_exceeded	422	Fix the request. Retrying as-is will not help
price_below_minimum	422	Fix the request. Retrying as-is will not help
readback_failed	500	The write already succeeded — do not retry. Fetch the current state with GET
set_inventory_must_be_null	422	Fix the request. Retrying as-is will not help
set_inventory_not_updatable	422	Fix the request. Retrying as-is will not help
set_nesting_forbidden	422	Fix the request. Retrying as-is will not help
sku_conflict	409	Conflict. Re-fetch the current state
status_locked	422	Fix the request. Retrying as-is will not help
ticket_info_required	422	Fix the request. Retrying as-is will not help
ticket_not_allowed	400 / 422	Fix the request. Retrying as-is will not help
too_many_axes	422	Fix the request. Retrying as-is will not help
too_many_axis_values	422	Fix the request. Retrying as-is will not help
too_many_variants	422	Fix the request. Retrying as-is will not help
total_inventory_changed	409	Nothing was written. The total changed after you read it. Read the item and orders again, recalculate, and send with a new Idempotency-Key
unlimited_inventory	422	Fix the request. Retrying as-is will not help
unsupported_kind	422	Fix the request. Retrying as-is will not help
variant_axis_mismatch	422	Fix the request. Retrying as-is will not help
variant_axis_missing	422	Fix the request. Retrying as-is will not help
variant_axis_value_unknown	422	Fix the request. Retrying as-is will not help
variant_id_required	422	Fix the request. Retrying as-is will not help
variant_item_inventory_must_be_null	422	Fix the request. Retrying as-is will not help
variant_not_found	422	Fix the request. Retrying as-is will not help
variation_incomplete	422	Fix the request. Retrying as-is will not help
variation_not_allowed	422	Fix the request. Retrying as-is will not help

Reservations, shipping, inflow routes

Code	HTTP	What to do
feature_not_enabled	403	Insufficient permission. Check the required scope
invalid_period	422	Fix the request. Retrying as-is will not help
invalid_reservation_state	409	Conflict. Re-fetch the current state
invalid_transition	409	Conflict. Re-fetch the current state
sold_out	409	Conflict. Re-fetch the current state
variant_reservation_not_supported	422	Fix the request. Retrying as-is will not help