Errors

Partial responses

A read endpoint can return part of its data instead of failing the whole request. When one section is temporarily unavailable, the response is still 200 with an errors[] array naming each affected section, while the rest of the data loads normally:

{
  "data": [ /* … the sections that loaded … */ ],
  "errors": [
    { "field": "pricing", "code": "downstream_timeout", "detail": "pricing temporarily unavailable" }
  ]
}

Treat a non-empty errors[] as this section is temporarily unavailable - render the rest and retry it, not a hard failure. An empty (or absent) errors[] means the whole response is fresh.

Hard failures

Hard failures use standard HTTP status codes:

Status	Meaning
401	Missing / malformed / unknown / revoked / expired key or shopper token
403	A publishable key on a privileged route, the wrong store, or an origin not on the key's allowlist
404	Not found, or a cross-customer resource accessed by URL
429	Rate limit exceeded - see Rate limits

Checkout over a credit limit returns a structured over_credit_limit state (with the shortfall), not a raw 409 - inspect the response body, don't just branch on the status code.

Next steps

• Rate limits - handling 429 and Retry-After.
• Authentication & keys - what triggers 401 / 403.

In the API Reference

Every operation lists its error responses. A good one to inspect:

• GET /v1/products - the errors[] partial-response envelope on a catalog read