ErrorKind

ErrorKind = CoreErrorKind | string & object

Stable SDK error kinds plus backend domain codes that pass through as strings.

Branch on this (or WarmHubError.kind) to recover from expected failures. isRetryable returns the retryability column verbatim.

Remarks

Stable kinds (members of CoreErrorKind):

• BACKEND — cause: server-side failure that did not carry a more specific domain code (tRPC error data has no data.warmhub.code, REST status mapped to the catch-all default — primarily 5xx that lack a body error.code — or an SDK transport throw such as a non-OK SSE response); retryable: true; action: retry with backoff and surface the message if it persists; if the underlying error is a deterministic local-adapter failure (e.g. a misconfigured custom fetch), fix the adapter rather than retrying; origin: SDK tRPC fallback, httpStatusToWarmHubCode default for unmapped HTTP statuses, SSE transport, unknown thrown values inside tRPC paths (custom-fetch adapter throws are normalized to BACKEND only on tRPC surfaces — on REST and ping surfaces the raw error escapes uncaught). REST responses with a parseable body surface as their pass-through error.code (typically INTERNAL_ERROR), and REST 4xx responses without a body code fall through to the HTTP-status mapping (NOT_FOUND, UNAUTHENTICATED, FORBIDDEN, CONFLICT, VALIDATION_ERROR, RATE_LIMITED), not BACKEND.
• NOT_FOUND — cause: a referenced entity (repo, org, thing, shape, subscription, credential set, etc.) is missing or the caller cannot see it; retryable: false; action: verify the identifier the call site used (wref, slug, name) and escalate to a caller with read access if the entity should exist; origin: SDK reads across all surfaces, commit pipeline, REST query endpoints
• FORBIDDEN — cause: caller is authenticated but lacks the required permission; retryable: false; action: request the missing permission or use a token with broader scope; origin: SDK + REST authorization middleware
• UNAUTHENTICATED — cause: missing, expired, or invalid bearer token on a tRPC or REST call; retryable: false; action: mint a fresh PAT and update whichever client option the application wires it into (auth.getToken callback or accessToken — the SDK does not read WH_TOKEN or any env var directly); wh auth login only refreshes the CLI’s on-disk credentials and does not propagate to a constructed SDK client; for export tickets, remint via the appropriate backend endpoint; origin: SDK + REST auth middleware. Live-ticket SSE auth failures surface as BACKEND, not UNAUTHENTICATED, because openSse maps every non-OK SSE response to BACKEND.
• VALIDATION_ERROR — cause: input failed schema, shape, or content-length validation; retryable: false; action: fix the offending field per the error message; origin: commit pipeline, SDK writes, client-side content limits
• CONFLICT — cause: write collides with current state (concurrent edit, name already in use); retryable: false; action: refetch the current state and reconcile before retrying the write; origin: commit pipeline, repo/org creation. Archived org / repo writes surface as the pass-through code ARCHIVED, not CONFLICT.
• RATE_LIMITED — cause: caller exceeded the per-token or per-org request budget; retryable: true; action: wait WarmHubError.retryAfter seconds before retrying; origin: REST + tRPC throttling
• CANCELLED — cause: caller aborted the request via AbortSignal; retryable: true; action: retry only if the caller still wants the result; origin: SDK AbortError mapping
• NETWORK — cause: connection failed before the server produced a response (DNS, refused, timeout, fetch error); retryable: true; action: check connectivity to the configured apiUrl and retry with backoff; origin: SDK fetchWithAuth connection-error mapping

Backend domain codes (e.g. SHAPE_MISMATCH, WREF_UNRESOLVABLE, UNRESOLVED_TOKEN, ARCHIVED, INTERNAL_ERROR) pass through unchanged on code / kind. Surface the message and hint verbatim and use the message to decide whether to retry — most pass-through codes are terminal, but the backend reuses some codes for transient failures (notably INTERNAL_ERROR, which the webhook-validation path emits with a please retry message when DNS or HEAD probes flake). See the HTTP error catalog for HTTP-status mapping and the most common backend codes (the catalog is not exhaustive — rarer codes such as UNRESOLVED_TOKEN and WREF_UNRESOLVABLE are emitted by the backend but not yet tabulated).