Docs

Errors

Every error is application/problem+json with a stable code. This page lists each code and its status.

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.

CodeStatusMeaning
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