> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> API error codes and how to handle them

# Error Handling

The API uses conventional HTTP status codes and returns structured JSON error responses.

## Error Response Format

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "field": "email",
      "message": "Invalid email format"
    }
  }
}
```

## HTTP Status Codes

| Status | Type                   | Meaning                                                             |
| ------ | ---------------------- | ------------------------------------------------------------------- |
| `400`  | `invalid_request`      | Bad request — invalid parameters or body                            |
| `401`  | `authentication_error` | Missing or invalid API key                                          |
| `403`  | `permission_error`     | Insufficient permissions (e.g., publishable key on admin route)     |
| `404`  | `not_found`            | Resource does not exist                                             |
| `409`  | `conflict`             | State conflict (e.g., insufficient stock, invalid state transition) |
| `429`  | `rate_limit`           | Too many requests — rate limit exceeded                             |
| `500`  | `server_error`         | Unexpected server error                                             |

## Error Codes

| Code                       | Status | Description                                      |
| -------------------------- | ------ | ------------------------------------------------ |
| `VALIDATION_ERROR`         | 400    | Request body or query validation failed          |
| `INVALID_CURRENCY`         | 400    | Currency mismatch with store currency            |
| `MISSING_API_KEY`          | 401    | No Authorization header provided                 |
| `INVALID_API_KEY`          | 401    | API key is invalid or expired                    |
| `INVALID_CUSTOMER_TOKEN`   | 401    | Customer JWT token is invalid                    |
| `RESOURCE_NOT_FOUND`       | 404    | Requested resource not found                     |
| `INSUFFICIENT_STOCK`       | 409    | Not enough inventory for the requested quantity  |
| `INVALID_STATE_TRANSITION` | 409    | Order state transition not allowed               |
| `CART_NOT_ACTIVE`          | 409    | Cart is already completed or abandoned           |
| `DISCOUNT_EXPIRED`         | 409    | Discount code has expired or reached usage limit |
| `RATE_LIMIT_EXCEEDED`      | 429    | Too many requests in the current window          |
| `INTERNAL_ERROR`           | 500    | Unexpected server error                          |

## Handling Errors

```typescript theme={null}
const res = await fetch('/v1/storefront/products/prod_nonexistent', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!res.ok) {
  const { error } = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // [RESOURCE_NOT_FOUND] Product with id 'prod_nonexistent' not found
}
```