Error Catalog

What you'll learn

• The standard error response format used across all API endpoints
• Every error code the API can return, organized by domain
• HTTP status codes and when each is used
• Best practices for handling errors in your frontend

Prerequisites

• Familiarity with the General Concepts guide
• Understanding of JSON error format
• Completed the Quick Start

Overview

The Blaze ECOM Storefront API uses a consistent error format across all endpoints. Every error response follows the JSON specification, returning one or more structured error objects in an errors array.

Errors are identified by a machine-readable code field (e.g., empty_cart, invalid_token) which stays stable across API versions, making it safe to match against in your frontend logic. The detail field provides a human-readable message suitable for displaying to end users.

Error Response Format

All error responses return a JSON body with the following structure:

{
  "errors": [
    {
      "code": "empty_cart",
      "status": 400,
      "detail": "The cart is empty.",
      "fields": [],
      "extra_info": {}
    }
  ]
}

Error Object Fields

Multiple Errors

A single response can contain multiple errors — for example, when an Ecto changeset validation fails on several fields:

{
  "errors": [
    {
      "code": null,
      "status": 422,
      "detail": "can't be blank",
      "fields": ["email"],
      "extra_info": {}
    },
    {
      "code": null,
      "status": 422,
      "detail": "can't be blank",
      "fields": ["password"],
      "extra_info": {}
    }
  ]
}

Extra Info Examples

Some errors include extra_info with additional context:

Cart already submitted — includes the order UUID so the frontend can redirect:

{
  "code": "cart_already_submitted",
  "status": 400,
  "detail": "This cart has already been submitted",
  "fields": [],
  "extra_info": {
    "order": { "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
  }
}

Invalid promo code — echoes back the code that was rejected:

{
  "code": "invalid_promo_code",
  "status": 400,
  "detail": "Coupon code does not exist.",
  "fields": ["promo_code"],
  "extra_info": {
    "promo_code": "SUMMER20"
  }
}

Invalid cart items — lists the items that are problematic:

{
  "code": "invalid_cart",
  "status": 400,
  "detail": "Invalid items in the cart",
  "fields": ["cart"],
  "extra_info": {
    "items": [{ "id": "item-uuid", "reason": "out_of_stock" }]
  }
}

POS API error codes — external error codes from integrated POS systems:

{
  "code": "bad_request",
  "status": 400,
  "detail": "Inventory type does not match",
  "fields": [],
  "extra_info": {
    "api_error_code": "TZ00003"
  }
}

HTTP Status Codes

Error Codes by Domain

Authentication Errors

OAuth & SSO Errors

User & Account Errors

Cart Errors

Order Errors

Payment Errors

Delivery & Address Errors

Store & Configuration Errors

Marketing & Promotions Errors

Loyalty & Rewards Errors

Identity Verification Errors

General Errors

Changeset Validation Errors

Ecto changeset errors are returned with HTTP status 422 and a null code. These are field-level validation errors that occur on create and update operations.

{
  "errors": [
    {
      "code": null,
      "status": 422,
      "detail": "can't be blank",
      "fields": ["email"],
      "extra_info": {}
    }
  ]
}

Common changeset validation messages include:

Handling Errors

General Strategy

1. Check status first — Route to the appropriate handler based on HTTP status code.
2. Match on code — Use the machine-readable code for specific error handling logic.
3. Display detail — Show the detail message to the user.
4. Use extra_info — Leverage additional context when available (e.g., redirect to an order on cart_already_submitted).

JavaScript Example

async function handleApiResponse(response) {
  if (response.ok) return response.json();

  const body = await response.json();
  const errors = body.errors || [];
  const firstError = errors[0];

  switch (response.status) {
    case 401:
      // Session expired or invalid credentials
      if (firstError?.code === "inactive_user") {
        showNotification("Your account has been deactivated.");
      } else {
        clearAuth();
        redirectToLogin();
      }
      break;

    case 403:
      redirectToLogin();
      break;

    case 404:
      showNotification("The requested resource was not found.");
      break;

    case 429:
      const retryAfter = response.headers.get("Retry-After") || 30;
      await delay(retryAfter * 1000);
      // Retry the request
      break;

    default:
      // Handle by error code
      handleErrorByCode(firstError);
  }
}

function handleErrorByCode(error) {
  switch (error?.code) {
    case "cart_already_submitted":
      const orderUuid = error.extra_info?.order?.uuid;
      if (orderUuid) redirectToOrder(orderUuid);
      break;

    case "cart_total_changed":
      revalidateCart();
      break;

    case "phone_number_requires_confirmation":
    case "email_requires_confirmation":
      redirectToVerification();
      break;

    case "out_of_stock":
    case "invalid_cart_item":
    case "invalid_cart":
      refreshCart();
      showNotification(error.detail);
      break;

    default:
      showNotification(error?.detail || "An error occurred.");
  }
}

Error Code Constants

Define error codes as constants to avoid typos:

const ErrorCodes = {
  EMPTY_CART: "empty_cart",
  INVALID_CART: "invalid_cart",
  INVALID_CART_ITEM: "invalid_cart_item",
  OUT_OF_STOCK: "out_of_stock",
  CART_ALREADY_SUBMITTED: "cart_already_submitted",
  CART_TOTAL_CHANGED: "cart_total_changed",
  INVALID_PROMO_CODE: "invalid_promo_code",
  DUPLICATE_PROMO_CODE: "duplicate_promo_code",
  PAYMENT_FAILED: "payment_failed",
  PHONE_REQUIRES_CONFIRMATION: "phone_number_requires_confirmation",
  EMAIL_REQUIRES_CONFIRMATION: "email_requires_confirmation",
  INVALID_TOKEN: "invalid_token",
  BAD_LOGIN: "bad_login",
  INACTIVE_USER: "inactive_user",
  MISSING_AUTHORIZATION: "missing_authorization_header",
  NO_DELIVERIES_AT_LOCATION: "no_deliveries_at_location",
};

Best Practices

1. Always check the errors array — Never assume a single error. Multiple validation errors can occur simultaneously.
2. Use code for logic, detail for display — Codes are stable; messages may change between versions.
3. Handle 401 globally — Set up a response interceptor that catches 401s and redirects to login.
4. Handle cart_already_submitted gracefully — Use the extra_info.order.uuid to redirect the user to their order instead of showing a raw error.
5. Handle cart_total_changed by re-validating — When prices change between cart load and submission, re-fetch the cart and ask the user to confirm.
6. Don't ignore fields — When fields is populated, highlight the relevant form fields for the user.
7. Log extra_info.api_error_code — POS-originated errors include an api_error_code that can help your support team diagnose issues.