# 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:

```json
{
  "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:

```json
{
  "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.