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

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