Skip to main content

​
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

StatusTypeMeaning
400invalid_requestBad request — invalid parameters or body
401authentication_errorMissing or invalid API key
403permission_errorInsufficient permissions (e.g., publishable key on admin route)
404not_foundResource does not exist
409conflictState conflict (e.g., insufficient stock, invalid state transition)
429rate_limitToo many requests — rate limit exceeded
500server_errorUnexpected server error

​
Error Codes

CodeStatusDescription
VALIDATION_ERROR400Request body or query validation failed
INVALID_CURRENCY400Currency mismatch with store currency
MISSING_API_KEY401No Authorization header provided
INVALID_API_KEY401API key is invalid or expired
INVALID_CUSTOMER_TOKEN401Customer JWT token is invalid
RESOURCE_NOT_FOUND404Requested resource not found
INSUFFICIENT_STOCK409Not enough inventory for the requested quantity
INVALID_STATE_TRANSITION409Order state transition not allowed
CART_NOT_ACTIVE409Cart is already completed or abandoned
DISCOUNT_EXPIRED409Discount code has expired or reached usage limit
RATE_LIMIT_EXCEEDED429Too many requests in the current window
INTERNAL_ERROR500Unexpected 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
}