Errors

Section-by-section degradation

Read endpoints degrade section by section rather than failing the whole response. A partial fan-out returns 200 with an errors[] array naming each degraded section while the healthy sections still populate:

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

Treat a non-empty errors[] as "this part is temporarily stale," not a hard failure - render what loaded and retry the degraded section. 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	Capability split (publishable on a privileged route), wrong merchant, off-allowlist Origin
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[] degradation envelope on a catalog read