Error codes

Envelope

// Every Throttle 4xx / 5xx response follows this shape.
{
  "error": {
    "code": "cart_already_checked_out",     // stable contract — use this
    "message": "Cart has already been converted to a draft order.",
    "details": [                            // optional, field-level
      { "field": "cartId", "code": "conflict", "message": "Already checked out" }
    ]
  }
}

Common codes

The list below covers the ~20 codes you'll see most often when integrating cart, checkout, payments, and embed flows. The full set is generated from the OpenAPI spec at api.usethrottle.dev/openapi.json.

Validation errors

When a zod body validator fails, the envelope carries code: "validation_error" and a per-field details[] array. Strict-input endpoints return only the canonical camelCase contract. Field-level details identify unrecognized keys and may include a suggestion string when the server can identify the intended field:

{
  "error": {
    "code": "validation_error",
    "message": "Request body validation failed",
    "details": [
      {
        "path": "",
        "message": "Unsupported field(s): unexpectedField",
        "code": "unrecognized_keys",
        "received": ["unexpectedField"]
      }
    ]
  }
}

SDK errors

Every Throttle SDK throws the same error class — ThrottleError from @usethrottle/errors, re-exported from each SDK. It carries code, statusCode, message, and optional details. The historical per-SDK names still work and are subclasses, so instanceof ThrottleApiError (cart) and instanceof ThrottleCheckoutError (checkout) keep working — and a single instanceof ThrottleError catches errors from all of them.

import { ThrottleError } from '@usethrottle/cart'; // same class in every SDK

try {
  await cart.items.add(cartId, item);
  await checkout.completeSession(sessionId, payment);
} catch (e) {
  if (e instanceof ThrottleError) {
    console.error(e.statusCode, e.code, e.message);
  } else {
    throw e;
  }
}

The cart SDK additionally throws typed subclasses for the two lifecycle failures worth branching on, so you don't have to sniff error.code strings. Both extend ThrottleApiError (and therefore ThrottleError): CartNotOpenError (409 cart_not_open) and CartNotFoundError (404).

import { CartNotOpenError } from '@usethrottle/cart';

try {
  await cart.shipping.select(cartId, method);
} catch (e) {
  if (e instanceof CartNotOpenError) {
    // The cart was converted by a completed order (terminal) or abandoned.
    // Rebuild a fresh cart from your last-known line items and retry.
    cartId = await rebuildCart();
  } else {
    throw e;
  }
}

HTTP code conventions

• 400 — request was malformed (validation, missing required field, invalid value).
• 401 — authentication missing or invalid (key, signature, JWT).
• 402 — request requires a paid subscription that isn't active (production entitlement).
• 403 — authenticated but not authorized for this workspace / application / role.
• 404 — resource doesn't exist (or exists in a different workspace).
• 409 — request conflicts with current state (cart already checked out, Idempotency-Key reused, slug taken).
• 410 — resource was permanently removed (revoked invitation, abandoned cart).
• 422 — semantic validation failed (e.g. payment amount exceeds order total).
• 429 — rate limit exceeded.
• 5xx — Throttle problem. Idempotency-Key replays do NOT cache 5xx, so safe to retry with the same key.