Responses & Errors

The REST API and the storefront GraphQL API report errors differently — REST uses HTTP status codes with a consistent JSON envelope, GraphQL always returns 200 with an errors array.

• 200 / 201 — Success. Checkdata in the response body.
• 400 — Bad request or validation failure. Check the errors array.
• 401 — Missing, invalid, expired, or revoked access token.
• 403 — Authenticated, but missing the required role (e.g. non-admin calling an admin route).
• 404 — Unknown resource id.
• 429 — Rate limit exceeded.

Every REST response — success or failure — uses the same shape:

{  "success": false,  "message": "validation failed",  "data": null,  "errors": [    { "field": "email", "tag": "email", "value": "" }  ],  "timestamp": "2026-07-18T10:15:00Z",  "path": "/v1/auth/login",  "method": "POST",  "request_id": "b7e1c9..."}

Include request_id when reporting an issue — it maps directly to a server-side log line.

The storefront GraphQL API returns HTTP 200 with an errors array alongside (or instead of) data, per the GraphQL spec. The official SDKs throw an ApiErrorwith the message and status code so you don't have to inspect the raw response shape.

The REST API is rate-limited per client. When exceeded, requests return 429 — back off and retry.