Error handling

Shape

• error_code — stable code you can use to handle the error programmatically.
• message — human-readable description of the error.
• errors — optional; per-field detail on validation errors.

{
  "error_code": "VALIDATION_ERROR",
  "message": "\"email\" is required",
  "errors": {
    "email": "required"
  }
}

Status codes

Retry strategy

Retry with exponential backoff on 429, 502, 503 and 504. Don't automatically retry other 4xx: they'll fail the same way.

Public Store API errors

The Store API has a separate error contract from the admin API. Every Store API error uses this shape:

• 400 invalid_request — invalid request, JSON, or parameters.
• 401 invalid_api_key, invalid_customer_token, or customer_authentication_required — a valid credential is missing.
• 402 store_api_subscription_required — inactive or unavailable API subscription.
• 403 insufficient_scope, api_key_type_not_permitted, or forbidden — the key type, scope, or permission is insufficient.
• 404 not_found or store_not_found — the API is disabled, or the store or resource is unavailable.
• 409 idempotency_conflict or commerce_conflict — idempotency conflict or incompatible purchase state; a pending operation needs reconciliation.
• 410 cart_link_expired — cart link expired.
• 422 invalid_selection — invalid product or availability selection.
• 429 rate_limit_exceeded — the per-minute limit was reached; honor Retry-After.
• 503 *_unavailable — a dependent service is unavailable.
• 500 store_api_error — unexpected internal error; contact support and include the request_id.

{"error":{"code":"invalid_request","request_id":"..."}}