Reference

Error codes

Every 4xx / 5xx response carries a stable error.code. Reach for it (not the prose message) when branching in your handler — codes are versioned with the wire contract; messages are not.

Envelope

4xx / 5xx error shape
// 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 .

error.codeHTTPCause
cart_not_found404Cart id is invalid or belongs to another workspace.
cart_not_open409A mutating cart operation targeted a cart no longer in status=open (converted by a completed order, or abandoned). In the cart SDK this surfaces as CartNotOpenError.
cart_already_checked_out409POST /carts/{id}/checkout was called twice on the same cart.
cart_already_converted409Cart is in status=converted (linked order is paid). Read-only.
customer_not_found404Customer id is invalid or belongs to another workspace.
order_has_subscription409The order belongs to a subscription, so it cannot be moved to another customer.
application_not_found404Application UUID is invalid or belongs to another workspace.
application_required400Endpoint requires X-Throttle-Application-Id header or applicationId in the body.
application_mismatch403API key is scoped to a different application than the request target.
application_key_workspace_route403API keys cannot access workspace-level routes (Clerk JWT required).
missing_application_id400POST /carts called without applicationId in the request body.
idempotency_key_reused409Same Idempotency-Key sent with a different request body within 24h.
invalid_origin400Origin in allowedOrigins isn't https://<host> or http://localhost:<port>; or it is a wildcard sent to the production environment, or a wildcard over a shared or public suffix. The message says which.
invalid_quote_token400pk_ token expired, scope-mismatched, or signed with a stale secret.
invalid_signature401Webhook signature failed verification (HMAC mismatch or stale timestamp).
embed_token_invalid401Provider embed JWT expired or was tampered with. Re-mint via the proxy endpoint.
embed_token_failed502The payment provider refused to mint an embed token (auth/permissions issue upstream).
permission_denied403Caller authenticated but lacks the required role / scope.
workspace_access_denied403Caller is not a member of the workspace in :workspaceId.
workspace_not_entitled_for_live402A production-environment credential was used without active subscription or partner status.
environment_mismatch403An API key or dashboard request contradicted its own environment: an API key sent an X-Throttle-Environment-Id for a different environment than the key belongs to, or a storefront session token was minted for a different environment. Use a key for the correct environment, or send the matching header. Fetching another environment’s resource by id answers 404 not_found, not this.
environment_not_found404Requested workspace environment does not exist, is archived, or is not accessible to the workspace.
member_env_forbidden403Clerk-authenticated member tried to use an environment outside their environment grants.
environment_slug_taken409A workspace environment with that slug already exists.
system_environment_locked400Production or another system environment cannot be archived.
validation_error400Request body failed zod validation, or a request value (such as a path id that is not a UUID) is not in the expected format. See details[] for field-level errors when present.
invalid_interval400Subscription cadence (create, change-plan, or a checkout recurring intent) named an out-of-vocabulary interval or unit, or a count of 0, negative, fractional, or above the unit max.
invalid_amount400A subscription amount of 0. On POST /subscriptions, PATCH /subscriptions/{id} and change-plan, send allowZeroAmount: true for a free or usage-only plan. A checkout session recurring.amount is the renewal price and must be above 0.
rate_limit_exceeded429Per-workspace rate limit hit. Retry-After header indicates the cooldown.
clerk_required403Endpoint requires a Clerk JWT (API key auth rejected).
workspace_mismatch403Clerk JWT workspace does not match the workspace in the URL.
no_file400Multipart upload route received a request without a file part.
mime_not_allowed415Upload file type is outside the route’s ALLOWED_MIME set.
logo_too_big413Logo upload exceeded the per-route byte cap.
asset_too_big413Email asset upload exceeded the per-route byte cap.
file_too_big413Digital-fulfillment upload exceeded the per-route byte cap.
fulfillment_not_found404Digital-upload route’s :id is not a fulfillment in this application.
fulfillment_not_digital404Upload route targeted a non-digital fulfillment type.
missing_token400Buyer download URL missing ?token= query param.
invalid_token401Buyer download token failed JWT verification.
token_mismatch401Buyer download token was minted for a different fulfillment.
download_expired410Buyer download window has elapsed.
download_limit_reached410Buyer download count has reached the configured limit for this delivery.
invalid_logo_url400logoUrl on /embed-config is not a valid https URL.
invalid_primary_color400primaryColor on /embed-config is not a #rrggbb hex string.
invalid_storefront_base_url400storefrontBaseUrl on /embed-config is not an absolute https URL.
image_url_unresolvable400A relative line-item imageUrl was sent but the application has no storefrontBaseUrl (or allowedOrigin) to resolve it against.

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.

error.codeHTTPCause
subscription_terms_undeterminable422A checkout session was created from an existing cart (hosted /cart/<id>, recovery link, cartId hand-off) whose subscription plan line has no usable plan reference or cadence, and no earlier session on the cart carries the intent. Refused before any charge.
recurring_customer_required422A recurring checkout session has no customer email or identifier, and none to inherit from an earlier session on the cart.
quantity_unchanged400change-quantity was called with the quantity the subscription already has. Checked before any charge.
invalid_subscription_state400An immediate or scheduled change that alters nothing (same plan, cadence and amount) ("Nothing to change"); pause on a subscription that is not active; resume on a cancelled or completed one.
invalid_state400 / 409 / 422The subscription (or invoice) is in a state that refuses the action. 400: recording usage on an installment plan. 409: cancelling with a refund a subscription that is already cancelled or completed, or scheduling a change while cancelAtPeriodEnd is true. 422: changing or reporting usage on a cancelled or completed subscription, an immediate change while paused, retry-charge / waive-period when not past due, or a prorated cancel with no unused time left.
installment_plan_locked409Amount, cadence, quantity or plan change on an installment plan (totalPayments set), or a manual period renew of a scheduled plan.
invalid_schedule400A custom installment schedule is malformed: not 2–60 rows, a gap on row 0, a later row without a valid gap (hour 1–8760, day 1–365, week 1–52, month 1–12), or an amount that is not a positive integer. The message names the row, e.g. "schedule[2].intervalCount: …".
schedule_first_payment_mismatch400A line unitPrice (or the POST /subscriptions amount) differs from schedule[0].amount.
installment_plan_merchant_only403A buyer session (or the subscription proxy) tried to pause, resume or cancel an installment plan.
renewal_needs_attention409An immediate change, retry-charge or waive-period on a subscription holding an unresolved orphan_charge renewalIssue. Scheduled changes and cancellation are still accepted.
payment_failed402The stored card declined during an immediate plan or seat change. Nothing changed.

Currency codes

Codes returned by the one currency rule on every create path, by per-currency amounts (discounts, shipping, routing thresholds) and by the main-currency lock. See Multi-currency for the rules behind them.

error.codeHTTPCause
currency_not_enabled422A create (cart, cart session, quote, order, subscription, checkout embed token, add-card token, import) sent a currency the store has not enabled: "{CUR} is not enabled for this store. Enabled: …". details: { currency, enabledCurrencies }, main currency first.
currency_not_supported422The code is not a supported ISO 4217 currency (for example XXX or a fund code), cannot be a main currency, or an external snapshot sent such a code: "{CUR} isn't a supported currency code." On a create, details: { currency, enabledCurrencies }.
currency_not_payable422No active connected payment service accepts the currency. On a payment path (finalize, checkout, authorize, payments, quote accept, embed tokens): "AUD can't be paid right now: no connected payment service accepts it." with details { currency, payableCurrencies }. On the embed-config PUT enable gate: "No connected payment service accepts CHF. Add or edit a connector first." with details an array of { currency, payableCurrencies }.
currency_coverage_unavailable503The embed-config PUT could not read payment coverage, so nothing changed: "Couldn't check payment coverage. Try again." Payment paths do not return this; they proceed.
currency_not_available_in_production422A production environment was asked for a non-USD currency before multi-currency opens in production, or a production cartCurrencies PUT added a code.
currency_mismatch422A payment sent a currency other than its order's (POST /orders/{id}/payments, /payments/record), a subscription linked to an order (orderId) sent a currency other than the order's, or the shipping configuration PUT sent a currency other than the main currency. details: { currency, orderCurrency } on the order and subscription paths.
currency_locked409PATCH of an application or store currency after its first production sale.
currency_required400The store currency could not be resolved on this deployment and the request named none. Should not happen; report it with meta.requestId, or send currency.
currency_context_missing500The store has no currency settings in any environment. Should not happen; report it with meta.requestId.
discount_currency_unsupported422On any cart or order: the code has no amount in its currency (a fixed_amount code), or another currency has a minimum and this one has none: "This code can't be used for orders in {CUR}." Nothing is applied. A percentage code with no minimum anywhere works in every currency.
shipping_currency_unsupported422On any cart: a shipping selection (POST /api/v1/carts/{id}/shipping) or an external snapshot (POST /api/v1/shipping-tax/external-snapshots) named a currency other than the cart's, or a calculation's selected rate is a non-zero amount in another currency. Nothing new is selected or saved; send the cart's currency or choose another method. At a cart-session checkout hand-off it carries details.shipping (see Line Resolvers).
calculation_currency_required400A shipping/tax calculation with a cartId was sent without currency.
quote_amounts_need_review422POST /quotes/{id}/issue while an amount typed in another currency is unconfirmed. details.pending lists them.
routing_amount_main_currency_required422A routing or decline amount condition has no threshold in the main currency while its currency condition admits it. Messages start "Rule N:" ("Decline rule N:" on the decline flows).
routing_amount_currency_excluded422An amount condition has a threshold for a currency the same rule's currency condition excludes, so it could never apply.
routing_too_many_rules422The rules compile to more than 25 processor rules (each currency threshold is its own rule). Remove rules or currency thresholds. Nothing was changed.
routing_rules_restore_failed502Saving routing or decline rules failed after the old rules were removed, and putting the old rules back failed too, so the flow may be missing rules. Review the rules and save them again. When the old rules are restored, the save answers the original error and its message says nothing was changed.

Order builder collect codes

Codes returned when collecting payment for a draft order built in the dashboard: the payment-link and invoice-on-terms routes, and the payment-link checkout page. See Build an order from a cart .

error.codeHTTPCause
order_not_draft409The order is not a draft built with POST /api/v1/orders/from-cart, or it already has a payment in progress.
order_has_no_cart409The order was not built from a cart, so it cannot take a payment link.
invoice_terms_not_connected409Invoice Terms (throttle_net30) is not connected in this application and environment.
invoice_in_progress409Another request is invoicing this order. Reload in a moment.
invoice_issue_failed502The invoice could not be issued, or the order was not fully updated after it was. Retrying finishes the same invoice; it never issues a second one.
payment_in_progress409The customer is paying the current payment link right now (for example, in 3-D Secure). Try again in a few minutes.
payment_link_conflict409The order's payment link changed while this request ran. Reload the order and retry.
payment_link_cancel_failed502The current payment link could not be cancelled, so it was not replaced or removed. Retry.
payment_link_details_locked409POST /api/v1/checkout-sessions/{id}/calculate on a payment link sent an email, address or VAT number other than the order's. The link pays the order as built; ask the merchant for a new order.

Resolved cart codes

Codes returned for carts whose lines an installed app prices, and for cart sessions of an environment that only allows prices from installed apps. Each code, its details shape and the SDK error class are on Line Resolvers .

error.codeHTTPCause
price_locked400A request sent a field only the app (or Throttle) may set: unitPrice, name, imageUrl, taxAmount or discountAmount on a resolved add, a price field or locked metadata key on an owned line, or a shipping amount that differs from Throttle's quote, or a cart-level tax override key (taxTrigger, shippingTaxCode, transport, deliveryTerms, isGoodsSecondHand, exchangeRate) in the metadata of a resolved cart session or under resolved lines only. details.fields names them.
quantity_unavailable409The app refused the quantity (OUT_OF_STOCK, QUANTITY_UNAVAILABLE, BELOW_MIN, ABOVE_MAX), or a line would pass 10,000 units. Nothing changed.
line_not_purchasable422The app refused the item (NOT_FOUND, NOT_PURCHASABLE, NO_PRICE_IN_CURRENCY, PRICE_SOURCE_MISMATCH); at the checkout hand-off, details.lines lists the refused lines.
line_resolver_unavailable503The app that prices the cart did not answer, or its installation is no longer usable. Nothing changed; retry.
line_resolver_not_available422lineResolver names an app that is not installed and active in this application and environment, or has no line resolver.
resolved_lines_required422The environment only accepts resolved lines in browser carts, and this cart session was created without lineResolver.
line_limit_reached422A cart already holds 50 lines priced by one app.
cart_prices_changed409At checkout, a price, an availability or the shipping amount changed; the cart now holds the new values. Review it and check out again.
cart_changed409The cart changed while a line was being added. Nothing was added; retry.
amount_too_large422A line or cart amount would exceed 2,147,483,647 minor units. Lower the quantity.
shipping_method_unavailable422Throttle does not quote that shipping method for the cart: often no address yet, or the method has no currencyAmounts entry for the cart's currency (a method is offered only in the currencies it has an amount for).
shipping_quote_unavailable503Shipping or tax for the cart cannot be quoted right now. Nothing changed; retry.

The two cart pricing settings on PUT /api/v1/embed-config, resolvedLinesOnly and cartCurrencies, answer 403 permission_denied to any caller other than the merchant (an installed app's key, an extension session, an OAuth token). An invalid cartCurrencies answers 400 validation_error with details[].path naming the field or the entry, for example cartCurrencies.1 for a duplicate, the environment's own currency, or a code that cannot be enabled (a fund or test code such as XTS, or one whose processor decimal places are unconfirmed, such as HUF or IDR). Extra cart currencies

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.

error.codeHTTPCause
no_changes400The body has no add, update or remove entries.
invalid_line_item400An update lineItemId or a remove id is not a line item on this order.
empty_order400The edit would remove every line item. An order keeps at least one.
not_found404No such order in the application and environment of the credential.
order_not_editable409The order is cancelled, refunded or voided.
subscription_order_not_editable409The order is backed by a subscription. Change the subscription plan instead.
order_edit_in_builder409The order is a draft built in the dashboard order builder (POST /api/v1/orders/from-cart). Cancel it and build a new one.
no_customer409The edit raises the total of an order with a captured payment, and the order has no customer whose stored card could be charged.
payment_failed402Charging the increase to the customer’s stored card failed. Nothing changed.
tax_origin_missing422The application calculates tax with a provider (taxMode: "app_based", e.g. Avalara) and has no origin address. Set it under Tax → Setup → Origin.
tax_address_missing422The application calculates tax with a provider, the order has no address its tax trigger can use, and the tax fallback policy is strict. Under lenient the edit goes through untaxed with a tax_address_missing warning.
tax_provider_unavailable503The tax provider could not answer and the tax fallback policy is strict (the default). Retry once the provider is reachable. Under lenient your native tax rules price the edit and the response carries a provider_fallback warning.
not_implemented501The edit raises the total of an order with a captured payment on a server that has no stored-card charging configured.

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:

validation_error
{
  "error": {
    "code": "validation_error",
    "message": "Request body validation failed",
    "details": [
  {
    "path": "",
    "message": "Unsupported field(s): unexpectedField",
    "code": "unrecognized_keys",
    "received": ["unexpectedField"]
  }
    ]
  }
}
Discover field names from error.details
When in doubt about a field name, send the request, then read error.details[].path. The validator names the canonical key it expected.

A malformed id (for example undefined or tmp_123 where a UUID is expected) also answers 400 validation_error, not a 5xx. When the route's path schema declares the UUID format, details[] names the parameter; otherwise the envelope has no details. Treat it as a client bug and do not retry.

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.

Catch every Throttle SDK error with one check
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).

Branch on a stale cart without sniffing error codes
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.