Errors

The error envelope and what every status code means.

Every Store API failure response shares one envelope. The HTTP status carries the kind of failure; the body carries the code, the message, and any per-error details.

Envelope#

json

{
  "success": false,
  "error": {
    "code":    "TAG_SLUG_DUPLICATE",
    "message": "A tag with that slug already exists.",
    "details": { "field": "slug" }
  }
}

Field	Description
`error.code`	Stable, screaming-snake-case identifier. Branch on this in code.
`error.message`	Single-sentence human-readable description.
`error.details`	Optional per-error context (offending field name, conflicting record ID, etc.). Documented per endpoint.

Status codes#

Status	Means	Retry
400	Request shape is wrong.	No.
401	Token missing, malformed, or expired.	No.
403	Token valid but lacks the required scope.	No.
404	Resource does not exist or your token cannot see it.	No.
409	Conflict — typically a duplicate or stale write.	Only with a different payload.
422	Semantic validation failure on a well-formed request.	No.
429	Rate-limited.	After `Retry-After` seconds.
5xx	Server-side failure.	Yes, with exponential backoff.

Per-endpoint errors#

Each endpoint's reference page lists the specific error codes it can return and what triggers them.