JavaScript SDK error classes, RetryPolicy, RequestOptions

TL;DR Every throw from @typesafe-ai/sdk 0.6.0 is a TypeSafeError. Catch APIError for HTTP failures (.status, .headers, .body, .requestId; RateLimitError adds .retryAfterMs), APIConnectionError for transport failures (APITimeoutError is a subclass carrying .timeoutMs), and APIUserAbortError for caller cancellation. By default the client retries 408/429/5xx plus connection errors and timeouts, twice, with 500 ms → 5 s exponential backoff and 25 % jitter, honouring Retry-After up to 60 s.

Hierarchy

Error
└── TypeSafeError                     base class for SDK errors
    ├── APIError                      an unsuccessful HTTP response
    │   ├── BadRequestError           400
    │   ├── AuthenticationError       401
    │   ├── PermissionDeniedError     403
    │   ├── NotFoundError             404
    │   ├── UnprocessableEntityError  422
    │   ├── RateLimitError            429  (+ retryAfterMs)
    │   └── InternalServerError       5xx
    ├── APIConnectionError            DNS/TLS/connection closed, interrupted body
    │   └── APITimeoutError           timeout  (+ timeoutMs)
    └── APIUserAbortError             caller aborted via AbortSignal

All twelve classes are exported from the package root. error.name is set from new.target.name in the TypeSafeError constructor, so err.name is the concrete subclass name ("RateLimitError", not "Error").

Class reference

TypeSafeError

"Base class for SDK errors." Extends Error.

new TypeSafeError(message: string, options?: ErrorOptions): TypeSafeError

Properties: those of Error (message, name, stack, cause). name is set to the constructing subclass's name.

Thrown directly (not as a subclass) for client-side problems:

APIError

"An unsuccessful HTTP response from the API." Extends TypeSafeError.

new APIError(status: number, body: unknown, headers: Headers, message?: string): APIError

Properties (all readonly, inherited unchanged by every subclass):

Static method:

static fromResponse(status: number, body: unknown, headers: Headers): APIError

"Create the error subclass for an HTTP status code." This is what the client calls for every non-2xx response.

Derived message. APIError builds message as "<status> <detail>", where detail is pulled from the body in this order: a plain string body; body.error when it is a string; body.error.message; body.message; body.detail when it is a string; body.detail.message; or, when body.detail is an array, FastAPI-style validation entries formatted as semicolon-separated path: message pairs (with a leading body segment in loc dropped). If nothing matches: "<status> status code (no body)" for an empty body, otherwise the raw body (JSON-stringified if needed), truncated to 200 characters with an ellipsis.

Status → class mapping

Exactly as implemented in APIError.fromResponse:

Note the gaps: 408 has no dedicated class even though it is retried by default, and 402/409 fall through to plain APIError. BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, UnprocessableEntityError and InternalServerError add no properties or methods of their own — they exist purely so you can branch with instanceof.

RateLimitError

Extends APIError; everything above plus:

Computed at construction from the response headers by parseRetryAfter, which prefers retry-after-ms (a finite non-negative number) and otherwise parses Retry-After either as seconds (converted to ms; negative → undefined) or as an HTTP date (converted to a non-negative delta from now).

APIConnectionError

"The request or response-body delivery failed (DNS, TLS, connection closed, etc.)." Extends TypeSafeError.

new APIConnectionError(message?: string, options?: ErrorOptions): APIConnectionError

No extra properties. In practice the client constructs it with `Connection error: ${err.message}` and { cause: err }, so the original TypeError/fetch failure is on .cause.

APITimeoutError

"The full response did not arrive within the timeout. A kind of APIConnectionError." Extends APIConnectionError.

new APITimeoutError(timeoutMs: number, options?: ErrorOptions): APITimeoutError

Message: Request timed out after <timeoutMs>ms. Because it extends APIConnectionError, catch (e) { if (e instanceof APIConnectionError) … } also catches timeouts — check APITimeoutError first if you need to tell them apart.

The timeout covers the whole round trip including body delivery: the client buffers the full response body under the same abort controller before resolving.

APIUserAbortError

"The caller cancelled the request through an AbortSignal." Extends TypeSafeError.

new APIUserAbortError(message?: string, options?: ErrorOptions): APIUserAbortError

Raised both when the signal fires during an attempt and when it fires while waiting to retry. It is never retried, regardless of policy.

RetryPolicy

"Retry configuration. Partial overrides inherit unset fields from the client or SDK defaults." All fields are readonly and required on the full interface; you pass Partial<RetryPolicy> to the client or to a call.

The defaults come from DEFAULT_RETRY_POLICY in src/retry.ts; DEFAULT_MAX_RETRIES is exported internally as 2 but is not part of the public package surface. DEFAULT_TIMEOUT_MS is 10_000.

How a delay is computed

retryDelayMs(attempt, headers, policy) (zero-based attempt):

1. If respectRetryAfter and response headers are present, parse retry-after-ms / Retry-After; if the value is defined and <= maxRetryAfterMs, use it as-is (no jitter).
2. Otherwise: exponential = min(backoffInitialMs * 2 ** attempt, backoffMaxMs), then round(exponential * (1 - random() * backoffJitter)).

With the defaults that is roughly 375–500 ms before the first retry and 750–1000 ms before the second.

What is retried

Retries are counted with an X-TypeSafe-Retry-Count header ("1", "2", …; absent on the first attempt). Each retry logs at info: #N POST /v1/systemone retrying in 412ms (retry 1/2) after 429.

Overrides are merged field by field: a call's retry inherits unset fields from the client's resolved policy, which itself inherits from DEFAULT_RETRY_POLICY. The status set is copied on merge, so mutating a Set you passed in afterwards has no effect.

RequestOptions

"Per-call options that override client settings." All optional; accepted as the second argument of client.systemOne() and the first of client.models.list().

Header merging is case-insensitive and last-value-wins; the SDK's own auth and protocol headers are applied after yours, so they cannot be overridden (see JavaScript/TypeScript SDK: install, client, choice/score/noul).

There is no maxRetries shorthand — write { retry: { maxRetries: 0 } }.

Example: try/catch with the full hierarchy

import {
  APIConnectionError,
  APIError,
  APITimeoutError,
  APIUserAbortError,
  AuthenticationError,
  BadRequestError,
  InternalServerError,
  NotFoundError,
  PermissionDeniedError,
  RateLimitError,
  TypeSafeClient,
  TypeSafeError,
  UnprocessableEntityError,
  choice,
} from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  timeout: 15_000,
  retry: { maxRetries: 3, backoffInitialMs: 250, maxRetryAfterMs: 30_000 },
});

const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard ceiling across all attempts

try {
  const { answers } = await client.systemOne(
    {
      state: { ticket: "I was charged twice." },
      questions: {
        category: choice("What is this ticket about?", {
          billing: null,
          technical: null,
          other: null,
        }),
      },
    },
    {
      signal: controller.signal,
      timeout: 8_000,
      retry: { httpStatuses: new Set([429, 500, 502, 503, 504]) },
      headers: { "X-Correlation-Id": "abc-123" },
    },
  );
  console.log(answers.category.choice);
} catch (err) {
  // Order matters: subclasses before their bases.
  if (err instanceof RateLimitError) {
    console.error(`rate limited; retry after ${err.retryAfterMs ?? "unknown"}ms`, err.requestId);
  } else if (err instanceof AuthenticationError || err instanceof PermissionDeniedError) {
    console.error(`auth problem ${err.status}:`, err.body); // do not retry
  } else if (err instanceof BadRequestError || err instanceof UnprocessableEntityError) {
    console.error(`bad request ${err.status}:`, err.message); // fix the payload
  } else if (err instanceof NotFoundError) {
    console.error("wrong baseURL or model?", err.status);
  } else if (err instanceof InternalServerError) {
    console.error(`server error ${err.status} (request ${err.requestId ?? "unknown"})`);
  } else if (err instanceof APIError) {
    // 402, 405, 409, 418, ... land here
    console.error(`API error ${err.status}:`, err.body, err.headers.get("x-typesafe-request-id"));
  } else if (err instanceof APITimeoutError) {
    console.error(`timed out after ${err.timeoutMs}ms`, err.cause);
  } else if (err instanceof APIConnectionError) {
    console.error("transport failure:", err.message, err.cause);
  } else if (err instanceof APIUserAbortError) {
    console.error("cancelled by caller");
  } else if (err instanceof TypeSafeError) {
    console.error("client-side problem:", err.message); // validation or config
  } else {
    throw err;
  }
}

CommonJS is identical apart from the import:

const { APIError, RateLimitError, TypeSafeClient, choice } = require("@typesafe-ai/sdk");

The minimal upstream form, from examples/demo.ts:

try {
  // ... client.systemOne(...)
} catch (err) {
  if (err instanceof APIError) {
    console.error(`API error ${err.status} (request ${err.requestId ?? "unknown"}):`, err.body);
  } else {
    throw err;
  }
}

Gotchas

• APITimeoutError extends APIConnectionError, so a bare instanceof APIConnectionError branch swallows timeouts. Check the more specific class first.
• No total retry budget. timeout is per attempt; with maxRetries: 3 a hung endpoint can consume 4 × timeout plus backoff. Use an AbortSignal for a wall-clock ceiling — it cancels pending retries too.
• Retry-After is used verbatim when <= maxRetryAfterMs, with no jitter, so a fleet retrying together will retry together. Lower maxRetryAfterMs or set respectRetryAfter: false if that matters.
• 408 is retried but has no subclass — it surfaces as a plain APIError with status === 408.
• body is unknown. Narrow it before use; it may be a parsed object, a raw string, or undefined.
• Aborting mid-body-read raises APIUserAbortError, not APIConnectionError, because the body buffer shares the caller's signal.
• err.requestId is the thing to log. It comes from x-typesafe-request-id and is what TypeSafe support will ask for.

Version notes

Described for @typesafe-ai/sdk 0.6.0 (repo commit 66880ccded6cb642dc1809620c2b108c33730214, 2026-09-15). Docs and source agree on every class, property and default listed here; the published per-class pages simply omit the message-derivation logic and the TypeSafeError message catalogue, which come from src/errors.ts and src/client.ts.

Related

• JavaScript/TypeScript SDK: install, client, choice/score/noul — client construction, defaults, headers
• JavaScript SDK interfaces and type aliases — RetryPolicy and RequestOptions in the wider type map
• HTTP status codes, rate limits, retry semantics — HTTP status semantics across all clients
• Python SDK retries, exceptions, constants — the Python equivalents
• HTTP API: POST /v1/systemone and GET /v1/models — status codes as the API defines them

Sources

• raw/docs/sdk__javascript__api__classes__TypeSafeError.md, __APIError.md, __APIConnectionError.md, __APITimeoutError.md, __APIUserAbortError.md, __BadRequestError.md, __AuthenticationError.md, __PermissionDeniedError.md, __NotFoundError.md, __UnprocessableEntityError.md, __RateLimitError.md, __InternalServerError.md (https://docs.typesafe.ai/sdk/javascript/api/classes/*)
• raw/docs/sdk__javascript__api__interfaces__RetryPolicy.md (https://docs.typesafe.ai/sdk/javascript/api/interfaces/RetryPolicy)
• raw/docs/sdk__javascript__api__interfaces__RequestOptions.md (https://docs.typesafe.ai/sdk/javascript/api/interfaces/RequestOptions)
• raw/github/typesafe-sdk-js/src/errors.ts, src/retry.ts, src/client.ts, src/types.ts, examples/demo.ts (commit 66880ccded6cb642dc1809620c2b108c33730214)