Error envelope

Every error response uses the same JSON shape, regardless of which endpoint or HTTP status code it came from.

{
  "error": "insufficient_scope",
  "message": "This key is missing required scope(s): orders:write.",
  "required_scopes": ["orders:write"]
}

HTTP	error	When
400	invalid_request	Body or query failed Zod validation.
400	invalid_id	Path param wasn't a UUID.
400	invalid_json	Body wasn't parseable JSON.
401	missing_token	No Authorization header.
401	invalid_token	Bearer doesn't resolve to a key.
401	revoked	Key was revoked.
401	expired	Key passed its expiry date.
403	wrong_mode	Live key on test store (or vice versa).
403	insufficient_scope	Key's scopes don't cover the route.
403	ip_not_allowed	Request IP not in the key's allowlist.
402	pro_required	API access needs Zillo Pro on the store. (Stores already using the API before Pro launched are unaffected.)
404	not_found	Resource id doesn't exist on this merchant.
409	already_redeemed_or_voided	Redeem on something already done.
429	rate_limited	Quota exceeded — see Retry-After.
500	internal	Bug on our end. Include X-Request-Id in support tickets.