Errors and localization

The GraphQL error and user-error response shape shared with CTX.

Errors and localization#

Storefront GraphQL uses GraphQL errors for request/authorization failures and response objects for mutation result messages. Both carry stable codes and localized human text.

Surface	Shape
GraphQL execution error	`errors[].extensions.code`, `locale`, `status_code`, `request_id`, and optional `details`.
Mutation payload message	`payload.response.code`, `message`, `locale`, and `params`.
Client behavior	Branch on stable codes. Display localized messages. Preserve `request_id` when contacting support.

json

{
  "errors": [
    {
      "message": "Localized message",
      "extensions": {
        "code": "UNAUTHORIZED",
        "locale": "en",
        "status_code": 401,
        "request_id": "018f..."
      }
    }
  ]
}

graphql

mutation CustomerLogin($input: CustomerLoginInput!) {
  customerLogin(input: $input) {
    success
    error
    response {
      code
      message
      locale
      params { key value }
    }
  }
}