Each error body has this shape. Quote request_id when you contact support.
{
"type": "string",
"title": "string",
"status": 401,
"code": "unauthorized",
"detail": "string",
"request_id": "string",
"upgrade_url": "string",
"tier": "string",
"errors": [
{
"path": "string",
"code": "string",
"message": "string"
}
]
} A validation error lists each field in errors[] with its path, such as targets[0].resource_id.
| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | No valid API token in Authorization: Bearer |
insufficient_scope | 403 | The token lacks the route's scope (see required_scope) |
not_found | 404 | No such endpoint, or the resource doesn't exist in this shop |
method_not_allowed | 405 | The path exists but not with this method |
invalid_json | 400 | The request body isn't valid JSON |
payload_too_large | 413 | The request body is over 1 MB |
invalid | 422 | Validation failed; errors[] names each field |
if_match_required | 428 | Send If-Match with the resource's ETag |
conflict | 412 | The resource changed since your ETag; read it again |
managed_by_drop | 409 | A drop manages this lock (see drop_id); edit the drop |
audience_in_use_by_drop | 409 | A drop's early access uses this audience (see drops) |
drop_started | 409 | The drop has launched; its launch, windows and sell mode are fixed |
raffle_drawn | 409 | The raffle has been drawn; its settings are fixed |
raffle_not_closed | 409 | Raffle entries are still open (they close at launch) |
drops_open | 409 | A raffle is open or a drop is between its teaser and public launch |
revocation_list_full | 422 | Checkout can't track more recent revocations; revoke fewer or wait |
tag_limit | 422 | Locks would check more than 100 customer tags |
scopes_required | 403 | The shop hasn't granted the access this needs (see scopes); grant it in the Shopbird admin |
plan_limit | 402 | The shop's plan doesn't cover this (see upgrade_url) |
tag_not_in_use | 422 | Only tags an audience uses can be set on customers |
idempotency_key_reused | 422 | This Idempotency-Key was used with a different request |
idempotency_key_in_flight | 409 | A request with this Idempotency-Key is still running |
rate_limited | 429 | Too many requests or wrong codes; wait for Retry-After |
temporarily_unavailable | 503 | Busy, or Shopify is throttling; retry after Retry-After |
internal_error | 500 | Unexpected failure; retry, and quote request_id to support |