Error handling

Both SDKs throw typed errors — never plain Error instances. This page is a recipe collection: pattern-match with instanceof to handle a specific failure mode, retry the ones that are safe to retry, and surface the rest. By the end you will have a catch block for every error class both SDKs can produce.

Recipe: catching errors from `@gavai/sdk`

The high-level client throws GavaiError for API-level failures and GavaiNetworkError for transport failures (DNS, connection refused, timeout). GavaiNetworkError does not extend GavaiError — check for it separately. GavaiError carries: Common code values you’ll see in production:

catch-public.ts

import { Gavai, GavaiError, GavaiNetworkError } from "@gavai/sdk";

const gv = new Gavai({ apiKey: process.env.GAVAI_API_KEY });

try {
  await gv.pages.publish({ workspace: "acme" });
} catch (e) {
  if (e instanceof GavaiError && e.code === "token_expired") {
    // Refresh the token and retry the call
    return;
  }
  if (e instanceof GavaiNetworkError) {
    // Transient connectivity failure — safe to retry with backoff
    return;
  }
  throw e;
}

Recipe: catching errors from `@gavai/sdk-typescript`

The low-level client uses a five-class hierarchy. Every class extends GavaiError.

catch-admin.ts

import {
  GavaiRateLimitError,
  GavaiSignatureError,
} from "@gavai/sdk-typescript/errors";

try {
  await client.workspaces.me();
} catch (err) {
  if (err instanceof GavaiRateLimitError) {
    await sleep(err.retryAfterSec * 1000);
    // retry...
  }
  if (err instanceof GavaiSignatureError) {
    // Never retry — the response could not be authenticated
    throw err;
  }
  throw err;
}

Recipe: retry safely

Recipe: log without leaking secrets

When you log an error, include at minimum: Do not log the full request headers or the Authorization header — they contain your API key. If you log e.details, scan it first for fields that might echo caller-supplied secrets.

JavaScript / TypeScript

Error handling

Recipe: catching errors from `@gavai/sdk`

Recipe: catching errors from `@gavai/sdk-typescript`

Recipe: retry safely

Recipe: log without leaking secrets

Next steps

​Recipe: catching errors from @gavai/sdk

​Recipe: catching errors from @gavai/sdk-typescript

​Recipe: retry safely

​Recipe: log without leaking secrets

​Next steps

Recipe: catching errors from `@gavai/sdk`

Recipe: catching errors from `@gavai/sdk-typescript`

Recipe: retry safely

Recipe: log without leaking secrets

Next steps