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 .

Subscription and recurring-checkout codes

Codes returned by the subscription routes and by checkout sessions that carry a plan. See Managing Subscriptions and Starting checkout from an existing cart for the behavior behind them.

Order line-item edit codes

Codes returned by PATCH /api/v1/orders/:id/line-items, which adds, updates or removes line items and settles the change on an order with a captured payment: an increase is charged to the stored card, a decrease refunded. On an order whose balance is on an outstanding Net-N invoice the invoice takes the change instead — its amount rises or falls, no card is charged — and the response reports it in data.adjustment.invoice. Every code below refuses the edit before anything is written, charged or refunded.

When the application calculates tax with a provider, the edit re-quotes tax with it. Under the lenient fallback policy a failure the strict policy refuses goes through instead, and the 200 response carries data.warnings: [{ code, message }]: provider_fallback (the provider could not answer, so your native tax rules priced the edit), tax_address_missing (no address to tax from, so no tax was charged), or tax_zero_from_provider (the provider returned no tax for the address). The field is absent when there is nothing to report. A refund that fails after the items changed does not error either: it comes back in data.adjustment.refundError, and the refund can be retried from the order. Likewise, a Net-N invoice the edit leaves owing nothing is voided, and a void that fails comes back in data.adjustment.invoice.voidError.

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.