Error codes

Every CrossdeckError the SDK can throw. Each entry has a stable code string, a human description, a one-sentence resolution, and a retryable flag indicating whether the SDK auto-recovers (no developer action needed) or whether the failure requires intervention. Same surface Stripe ships at stripe.com/docs/error-codes.

TL;DR

• Every error the SDK throws is a CrossdeckError with a stable type + code.
• Catch by code for specific recovery (code === "environment_mismatch") or by type for broad categories (type === "authentication_error").
• retryable: true errors are handled by the SDK's built-in retry — your code doesn't need to do anything special.
• The same list ships as a machine-readable JSON sidecar at @cross-deck/web/error-codes.json for AI assistants, error dashboards, and tooling.

CrossdeckError shape

import { CrossdeckError } from "@cross-deck/web";

try {
  await Crossdeck.identify("");
} catch (err) {
  if (err instanceof CrossdeckError) {
    err.type;        // "invalid_request_error"
    err.code;        // "missing_user_id"
    err.message;     // human-readable
    err.requestId;   // server-issued; quote in support tickets
    err.status;      // HTTP status if the error came from an API response
    err.retryAfterMs;// server's Retry-After when present
  }
}

Eight distinct type values group errors into broad categories:

Configuration errors

Thrown synchronously by Crossdeck.init(). Not retryable — fix the init options.

Validation errors

Thrown when SDK method arguments don't meet the contract. Not retryable — fix the call site.

Network errors

Transport-layer failures. Retryable — the SDK's built-in exponential-backoff retry handles them automatically for the event queue. Manual API calls (identify, getEntitlements, syncPurchases) surface them to the caller.

Internal errors

Crossdeck-side bugs or transient outages.

Full table

The complete reference, sorted by type. The SDK exports the same list at runtime as CROSSDECK_ERROR_CODES, and ships it as a sidecar JSON for tooling.

import { CROSSDECK_ERROR_CODES, getErrorCode } from "@cross-deck/web";

CROSSDECK_ERROR_CODES;
// → ErrorCodeEntry[] — same shape as the table above

getErrorCode("environment_mismatch");
// → { code, type, description, resolution, retryable }

Server-side errors that come back via the API (rate limits, permission denials, validation failures) follow Stripe's envelope format — { error: { type, code, message, request_id } } — and surface as CrossdeckError with the appropriate status. The code values for those are issued server-side and may extend the list above.

Machine-readable JSON

For AI assistants, error-aggregator dashboards, and any tooling that wants the table without booting a JavaScript runtime, the SDK ships a sidecar JSON file in the npm tarball:

node_modules/@cross-deck/web/dist/error-codes.json

Shape:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "generatedAt": "2026-05-11T11:23:00.000Z",
  "sdk": "@cross-deck/web",
  "codes": [
    {
      "code": "environment_mismatch",
      "type": "configuration_error",
      "description": "The publishable key's env prefix doesn't match the declared environment option.",
      "resolution": "Either change `environment` to match the key prefix (cd_pub_test_ ↔ sandbox, cd_pub_live_ ↔ production), or swap the key for one minted in the right env.",
      "retryable": false
    },
    ...
  ]
}

It is also reachable via the unpkg CDN at https://unpkg.com/@cross-deck/web@^1/dist/error-codes.json for tooling that doesn't pull the package into its dependency tree.

Handling errors in app code

Two patterns. Pick by intent.

Catch a specific code for recovery

try {
  await Crossdeck.identify(userId, { traits });
} catch (err) {
  if (err instanceof CrossdeckError && err.code === "environment_mismatch") {
    // Re-init with the right env, or surface a developer-facing toast.
  } else {
    // Unknown error — surface generically + log.
    console.error("identify failed:", err);
  }
}

Branch by category for broad strokes

if (err instanceof CrossdeckError) {
  switch (err.type) {
    case "authentication_error":
      // API key is bad — alert the developer, not the user.
      break;
    case "rate_limit_error":
      // Honour err.retryAfterMs — back off.
      break;
    case "network_error":
      // Transient. SDK auto-retries the event queue; manual calls fail.
      break;
  }
}

This list reflects @cross-deck/web@1.9.1. New codes added in future releases will appear here in lockstep with the SDK source at sdks/web/src/error-codes.ts.