Errors and rate limits

The error envelope

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is not valid.",
    "requestId": "8f3c2a9e-1b4d-4f6a-9c2e-7d5b3a1f0e64",
    "issues": [{ "path": "limit", "message": "Must be a whole number from 1 to 100." }]
  }
}

• error.code is stable; branch on it, never on the message. error.requestId identifies the request when you ask for help.
• error.issues (at most 20) names the fields at fault, as { path, message }.
• CART_REJECTED adds error.throttleCode, and CART_ITEMS_INVALID adds a top-level items list of refused lines.
• Throttle's cart-session routes answer their own envelope, { error: { code, message, details? } }, with lowercase codes.

The SDK's errors

Everything the SDK throws is a CatalogError (which extends ThrottleError from @usethrottle/errors), with code, message, statusCode (0 when nothing answered), source ('catalog', 'throttle' for Throttle's cart session, or 'client' when the SDK made it), retryable, retryAfterSeconds, issues, details and requestId.

import {
  CartLineError,
  createCatalogClient,
  CustomerTokenInvalidError,
  FeatureUnavailableError,
  isCatalogError,
  NetworkError,
  OriginNotAllowedError,
  RateLimitedError,
  TimeoutError,
} from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

try {
  await catalog.products.list({ q: 'brake pads' });
} catch (error) {
  if (error instanceof RateLimitedError) {
    // Every 429. The client never retries one itself.
    console.warn(`Slow down: retry in ${error.retryAfterSeconds} s`);
  } else if (error instanceof TimeoutError || error instanceof NetworkError) {
    console.warn('No answer; safe to try again.');
  } else if (error instanceof OriginNotAllowedError) {
    console.error('This website is not on the key’s allowed websites.');
  } else if (error instanceof FeatureUnavailableError) {
    console.error('This catalog does not have that route yet.');
  } else if (error instanceof CustomerTokenInvalidError || error instanceof CartLineError) {
    console.error(error.code);
  } else if (isCatalogError(error)) {
    // Everything else: branch on the code. source says who answered.
    console.error(error.code, error.statusCode, error.source, error.requestId, error.issues);
  } else {
    // Your own AbortSignal's reason, or a bug: not a catalog error.
    throw error;
  }
}

• FeatureUnavailableError. A 404 that carries the header X-Catalog-Route: unmatched means the catalog has no such route: an older catalog than the SDK. A 404 from a route that never answers a missing resource (config, the category tree, tags, the collections list, suggest, carts/check and carts) means the same. Any other 404 is NOT_FOUND.
• Your own abort rethrows your AbortSignal's reason, never wrapped in a CatalogError.
• isCatalogError also recognises an error from another copy of the SDK, such as the CommonJS build in an app that loads both; instanceof on a class holds within one build only.

Codes the SDK makes

Timeouts. timeoutMs (10 seconds by default, per client or per call) covers one request. Reading the customer token gets its own full timeoutMs first, so a call that waits on a slow token refresh can take up to about twice as long.

Every storefront error code

Every code a /v1/storefront route answers, from the OpenAPI document, with the class the SDK throws for it. Retryable means the same request may succeed later.

Throttle's cart-session codes (quantity_unavailable, cart_prices_changed, cart_session_expired and the others) reach you with source: 'throttle'; they are listed on Cart and checkout.

Rate limits

• Review submission adds 5 attempts a minute per customer and 10 accepted reviews an hour per IP address (server keys skip the IP cap).
• Over a limit the answer is 429 RATE_LIMITED with Retry-After in seconds. Wait that long; the SDK exposes it as RateLimitedError.retryAfterSeconds.
• The client never retries a 429 itself, so a burst never turns into a retry storm.
• The per-visitor count is kept per Cloudflare location and is approximate: a fast burst can pass somewhat more than the limit before it is refused. The per-key limit still caps a key.

In the hooks. A catalog 429 RATE_LIMITED that a read hook or a useCart change meets pauses every read of its CatalogProvider until retryAfterSeconds:

• The hook that met it keeps its data and shows the RateLimitedError.
• A hook mounted during the pause makes no request. With nothing cached for its query, it shows a RateLimitedError with the seconds left, not a loading state; with a cached answer, it shows that.
• useCart and useSubmitReview actions reject at once with that error, with no request.
• When the pause ends, each mounted query fetches once.
• Every other 429 goes to the caller only and pauses nothing: a 429 from Throttle's cart session, and every 429 from a review submit (RATE_LIMITED from the per-customer limit or the per-IP review cap, and REVIEW_QUEUE_FULL).

While the catalog is indexing

When a store first turns on the storefront, the catalog builds its storefront index. Until it is done, plain product browsing answers 200 with indexing: true (no filters, and a null total), and requests that need the index answer 503 STOREFRONT_INDEXING with Retry-After: 30. See the first backfill.

• The client retries a read once after Retry-After when that is 30 seconds or less (indexingRetry: { maxWaitSeconds } changes it, false turns it off); otherwise it throws with retryAfterSeconds.
• The hooks never wait inside a call. They show the 503 and fetch once more at Retry-After; a list answered with indexing: true is fetched once more after 30 seconds.