Error Handling

The GraphQL Storefront API returns errors in a structured format to help you diagnose and resolve issues quickly.

Mutation Errors: userErrors

For mutations, errors related to user input or business logic are returned in a userErrors array within the response. Each userError object typically contains the following fields:

• field: The input field(s) that caused the error (as an array of strings).
• error: A human-readable error message describing the problem.
• code: A short, machine-readable error code for programmatic handling.

Example mutation error response:

{
  "data": {
    "createOrder": {
      "userErrors": [
        {
          "field": ["email"],
          "error": "Email is required.",
          "code": "REQUIRED"
        }
      ],
      "order": null
    }
  }
}

Always check the userErrors array when handling mutation responses and display relevant messages to users. You can use the code field for custom error handling in your application.

Query Errors: HTTP Status Codes

For queries and general API requests, errors are communicated using standard HTTP status codes. Common codes include:

• 400 (Bad Request): The query is empty or malformed.
• 401 (Unauthorized): Authentication required (not currently enforced, but may be in the future).
• 402 (Payment Required): Payment required or merchant account is locked.
• 403 (Forbidden): Access denied or insufficient permissions.
• 404 (Not Found): The requested resource does not exist.
• 410 (Gone): The requested API version is no longer supported.
• 422 (Unprocessable Entity): Input validation errors.
• 429 (Too Many Requests): Rate limiting or throttling has been applied.

Example error response:

{
  "errors": [
    {
      "message": "Resource not found.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["products"]
    }
  ]
}

Always check the errors field in the response and handle errors gracefully in your application. For mutations, also check the userErrors array for actionable feedback.