Errors & retries

How the TypeScript SDK surfaces failures, and its automatic retry behavior for transient errors.

Catching errors

Every API and network error raises a typed FetchError rather than returning an error-shaped result. A successful scan never needs an error check beyond your normal try/catch.

import { TawaGuard, FetchError } from "@tawaguard/sdk";

try {
  const tawa = await TawaGuard.create(apiKey);
  const result = await tawa.analyze(userInput);
} catch (err) {
  if (err instanceof FetchError) {
    console.error(err.message); // error description
    console.error(err.status); // HTTP status code (or null for network errors)
    console.error(err.retryable); // whether a retry could succeed
  }
}

Automatic retries

The client retries transient failures automatically — up to 3 attempts by default, with exponential backoff and jitter between them:

429 (rate limited) — honors a Retry-After header when the server sends one, falls back to backoff otherwise.
5xx (server errors) — same backoff, no Retry-After expected.
Network errors (connection failures, timeouts) — retried the same way.

Anything else — 4xx other than 429, or exhausting the retry budget — raises immediately. retryable on the caught error tells you whether the SDK already gave up on a retryable class of error (all attempts exhausted) or the error was never retryable to begin with (e.g. a 401).

The retry count and backoff aren't tunable constructor options today — every request runs with the fixed defaults above (3 attempts, exponential backoff), and there's no configurable request timeout. If you need different retry behavior, wrap calls yourself, or see the API Reference for the underlying HTTP contract (rate limits, Retry-After, recommended backoff) if you're layering your own retry logic on top.

See the API Reference's error shape for the raw HTTP status codes and error object behind FetchError.

Catching errors

Automatic retries

On this page