Error Handling

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

Error Response Format

{
  "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

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
}