Errors

The API uses standard HTTP status codes. Error responses have a JSON body with a
short, stable machine-readable code in detail:

{ "detail": "insufficient_scope:data:write:products" }

Check the HTTP status first, then branch on detail for specifics. The codes
are stable strings you can match on.

Status codes

Status	Meaning
`200`	Success
`201`	Created
`202`	Accepted — queued for background processing (e.g. a message send or a channel sync)
`400`	Bad request — a value was invalid or a required field was missing
`401`	Not authenticated — missing, malformed, or revoked key
`403`	Authenticated, but not allowed — missing scope or permission
`404`	Not found — unknown resource, id, or an object not in your entity
`405`	The operation isn't available for this resource
`409`	Conflict — a uniqueness rule was violated (e.g. duplicate slug)
`422`	The request was understood but could not be processed
`429`	Rate limit exceeded (see Rate limits)
`502`	An upstream provider (e.g. a sales-channel sync) failed

Common error codes

Authentication (401)

missing_bearer_token — no Authorization: Bearer … header.
invalid_token — the token isn't a Zingasuite key.
invalid_or_revoked_key — the key is unknown, revoked, or expired.

Authorization (403)

insufficient_scope:<scope> — the key lacks a required scope, e.g.
insufficient_scope:data:write:products.
permission_denied:<op>:<model> — the key's owner can't perform this
operation on this object type, e.g. permission_denied:update:products.
membership_revoked — the key owner is no longer an active member of the
entity.
website_not_in_entity — the websiteId you passed doesn't belong to your
entity.

Requests (400 / 404 / 405 / 409 / 422)

missing_required:<field> — a required field was omitted.
unknown_resource / resource_not_available:<key> — no such generic
resource, or it isn't exposed on the API.
use_dedicated_endpoint:<key> — use the purpose-built endpoint instead of the
generic layer (for products, orders, inventory, websites).
resource_not_creatable / resource_not_updatable — the resource doesn't
support that operation on the API.
duplicate / slug_exists_under_parent — a uniqueness rule was violated.
provide_priceCents_or_tiers — supply exactly one of a flat price or a tier
ladder when setting prices.

Because codes are stable, you can build reliable handling — for example, treat
any insufficient_scope:* as "widen this key's scopes" and any 409 duplicate
as "already exists".