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
// 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.code | HTTP | Cause |
|---|---|---|
cart_not_found | 404 | Cart id is invalid or belongs to another workspace. |
cart_not_open | 409 | A 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_out | 409 | POST /carts/{id}/checkout was called twice on the same cart. |
cart_already_converted | 409 | Cart is in status=converted (linked order is paid). Read-only. |
customer_not_found | 404 | Customer id is invalid or belongs to another workspace. |
order_has_subscription | 409 | The order belongs to a subscription, so it cannot be moved to another customer. |
application_not_found | 404 | Application UUID is invalid or belongs to another workspace. |
application_required | 400 | Endpoint requires X-Throttle-Application-Id header or applicationId in the body. |
application_mismatch | 403 | API key is scoped to a different application than the request target. |
application_key_workspace_route | 403 | API keys cannot access workspace-level routes (Clerk JWT required). |
missing_application_id | 400 | POST /carts called without applicationId in the request body. |
idempotency_key_reused | 409 | Same Idempotency-Key sent with a different request body within 24h. |
invalid_origin | 400 | Origin 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_token | 400 | pk_ token expired, scope-mismatched, or signed with a stale secret. |
invalid_signature | 401 | Webhook signature failed verification (HMAC mismatch or stale timestamp). |
embed_token_invalid | 401 | Provider embed JWT expired or was tampered with. Re-mint via the proxy endpoint. |
embed_token_failed | 502 | The payment provider refused to mint an embed token (auth/permissions issue upstream). |
permission_denied | 403 | Caller authenticated but lacks the required role / scope. |
workspace_access_denied | 403 | Caller is not a member of the workspace in :workspaceId. |
workspace_not_entitled_for_live | 402 | A production-environment credential was used without active subscription or partner status. |
environment_mismatch | 403 | An 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_found | 404 | Requested workspace environment does not exist, is archived, or is not accessible to the workspace. |
member_env_forbidden | 403 | Clerk-authenticated member tried to use an environment outside their environment grants. |
environment_slug_taken | 409 | A workspace environment with that slug already exists. |
system_environment_locked | 400 | Production or another system environment cannot be archived. |
validation_error | 400 | Request 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_interval | 400 | Subscription 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_amount | 400 | A 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_exceeded | 429 | Per-workspace rate limit hit. Retry-After header indicates the cooldown. |
clerk_required | 403 | Endpoint requires a Clerk JWT (API key auth rejected). |
workspace_mismatch | 403 | Clerk JWT workspace does not match the workspace in the URL. |
no_file | 400 | Multipart upload route received a request without a file part. |
mime_not_allowed | 415 | Upload file type is outside the route’s ALLOWED_MIME set. |
logo_too_big | 413 | Logo upload exceeded the per-route byte cap. |
asset_too_big | 413 | Email asset upload exceeded the per-route byte cap. |
file_too_big | 413 | Digital-fulfillment upload exceeded the per-route byte cap. |
fulfillment_not_found | 404 | Digital-upload route’s :id is not a fulfillment in this application. |
fulfillment_not_digital | 404 | Upload route targeted a non-digital fulfillment type. |
missing_token | 400 | Buyer download URL missing ?token= query param. |
invalid_token | 401 | Buyer download token failed JWT verification. |
token_mismatch | 401 | Buyer download token was minted for a different fulfillment. |
download_expired | 410 | Buyer download window has elapsed. |
download_limit_reached | 410 | Buyer download count has reached the configured limit for this delivery. |
invalid_logo_url | 400 | logoUrl on /embed-config is not a valid https URL. |
invalid_primary_color | 400 | primaryColor on /embed-config is not a #rrggbb hex string. |
invalid_storefront_base_url | 400 | storefrontBaseUrl on /embed-config is not an absolute https URL. |
image_url_unresolvable | 400 | A 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.code | HTTP | Cause |
|---|---|---|
subscription_terms_undeterminable | 422 | A 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_required | 422 | A recurring checkout session has no customer email or identifier, and none to inherit from an earlier session on the cart. |
quantity_unchanged | 400 | change-quantity was called with the quantity the subscription already has. Checked before any charge. |
invalid_subscription_state | 400 | An 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_state | 400 / 409 / 422 | The 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_locked | 409 | Amount, cadence, quantity or plan change on an installment plan (totalPayments set), or a manual period renew of a scheduled plan. |
invalid_schedule | 400 | A 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_mismatch | 400 | A line unitPrice (or the POST /subscriptions amount) differs from schedule[0].amount. |
installment_plan_merchant_only | 403 | A buyer session (or the subscription proxy) tried to pause, resume or cancel an installment plan. |
renewal_needs_attention | 409 | An immediate change, retry-charge or waive-period on a subscription holding an unresolved orphan_charge renewalIssue. Scheduled changes and cancellation are still accepted. |
payment_failed | 402 | The 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.code | HTTP | Cause |
|---|---|---|
currency_not_enabled | 422 | A 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_supported | 422 | The 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_payable | 422 | No 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_unavailable | 503 | The 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_production | 422 | A production environment was asked for a non-USD currency before multi-currency opens in production, or a production cartCurrencies PUT added a code. |
currency_mismatch | 422 | A 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_locked | 409 | PATCH of an application or store currency after its first production sale. |
currency_required | 400 | The 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_missing | 500 | The store has no currency settings in any environment. Should not happen; report it with meta.requestId. |
discount_currency_unsupported | 422 | On 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_unsupported | 422 | On 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_required | 400 | A shipping/tax calculation with a cartId was sent without currency. |
quote_amounts_need_review | 422 | POST /quotes/{id}/issue while an amount typed in another currency is unconfirmed. details.pending lists them. |
routing_amount_main_currency_required | 422 | A 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_excluded | 422 | An amount condition has a threshold for a currency the same rule's currency condition excludes, so it could never apply. |
routing_too_many_rules | 422 | The 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_failed | 502 | Saving 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.code | HTTP | Cause |
|---|---|---|
order_not_draft | 409 | The order is not a draft built with POST /api/v1/orders/from-cart, or it already has a payment in progress. |
order_has_no_cart | 409 | The order was not built from a cart, so it cannot take a payment link. |
invoice_terms_not_connected | 409 | Invoice Terms (throttle_net30) is not connected in this application and environment. |
invoice_in_progress | 409 | Another request is invoicing this order. Reload in a moment. |
invoice_issue_failed | 502 | The 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_progress | 409 | The customer is paying the current payment link right now (for example, in 3-D Secure). Try again in a few minutes. |
payment_link_conflict | 409 | The order's payment link changed while this request ran. Reload the order and retry. |
payment_link_cancel_failed | 502 | The current payment link could not be cancelled, so it was not replaced or removed. Retry. |
payment_link_details_locked | 409 | POST /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.code | HTTP | Cause |
|---|---|---|
price_locked | 400 | A 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_unavailable | 409 | The 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_purchasable | 422 | The 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_unavailable | 503 | The app that prices the cart did not answer, or its installation is no longer usable. Nothing changed; retry. |
line_resolver_not_available | 422 | lineResolver names an app that is not installed and active in this application and environment, or has no line resolver. |
resolved_lines_required | 422 | The environment only accepts resolved lines in browser carts, and this cart session was created without lineResolver. |
line_limit_reached | 422 | A cart already holds 50 lines priced by one app. |
cart_prices_changed | 409 | At checkout, a price, an availability or the shipping amount changed; the cart now holds the new values. Review it and check out again. |
cart_changed | 409 | The cart changed while a line was being added. Nothing was added; retry. |
amount_too_large | 422 | A line or cart amount would exceed 2,147,483,647 minor units. Lower the quantity. |
shipping_method_unavailable | 422 | Throttle 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_unavailable | 503 | Shipping 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.code | HTTP | Cause |
|---|---|---|
no_changes | 400 | The body has no add, update or remove entries. |
invalid_line_item | 400 | An update lineItemId or a remove id is not a line item on this order. |
empty_order | 400 | The edit would remove every line item. An order keeps at least one. |
not_found | 404 | No such order in the application and environment of the credential. |
order_not_editable | 409 | The order is cancelled, refunded or voided. |
subscription_order_not_editable | 409 | The order is backed by a subscription. Change the subscription plan instead. |
order_edit_in_builder | 409 | The order is a draft built in the dashboard order builder (POST /api/v1/orders/from-cart). Cancel it and build a new one. |
no_customer | 409 | The edit raises the total of an order with a captured payment, and the order has no customer whose stored card could be charged. |
payment_failed | 402 | Charging the increase to the customer’s stored card failed. Nothing changed. |
tax_origin_missing | 422 | The 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_missing | 422 | The 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_unavailable | 503 | The 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_implemented | 501 | The 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:
{
"error": {
"code": "validation_error",
"message": "Request body validation failed",
"details": [
{
"path": "",
"message": "Unsupported field(s): unexpectedField",
"code": "unrecognized_keys",
"received": ["unexpectedField"]
}
]
}
} 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.
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.