Error handling

Most failed validation and domain errors return JSON with an errors array. Each item typically includes a field code (often the input key) and a human-readable message.

Validation example

{
  "errors": [
    {
      "code": "email",
      "message": "The email field is required."
    }
  ]
}

Auth failure

Missing or invalid Bearer tokens on auth:api (and equivalent vendor/driver guards) yield HTTP 401 / unauthorized responses. Clients should clear the stored token and return the user to login or guest session flows.

HTTP status conventions

• 200 / 201 — success
• 403 — authenticated but not allowed
• 404 — unknown resource
• 422 — validation / business-rule rejection (common for form requests)
• 429 — rate limited
• 5xx — server / upstream failure

Tips for integrators

• Always send zoneId and X-localization on storefront calls that depend on zone-scoped catalogs.
• Distinguish guest sessions from Passport customer tokens when debugging cart/order errors.
• Admin support routes fail closed without a valid X-Web-Admin-Support-Key.