> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Handle errors and retries
> Catch typed errors, back off correctly, and use idempotency keys so retries never double-charge.
export const ErrorTable = ({errors}) =>
;
export const Eyebrow = ({label, tone = "default"}) =>
{label}
;
By the end of this guide your integration catches typed errors instead of strings, retries only the errors that are safe to retry, backs off with jitter so a rate limit does not compound, and attaches an idempotency key on every write so a retried call never creates a duplicate.
## Prerequisites
The `@gavai/sdk` package installed. See [Your first integration](/guides/first-integration) if you have not set it up.Basic familiarity with HTTP status codes.
## Steps
The SDK throws `GavaiError` for every API-level failure. Branch on `e.code`, not on string matching against `e.message`.
```ts theme={null}
import { Gavai, GavaiError } from "@gavai/sdk";
const gv = new Gavai({ apiKey: process.env.GAVAI_API_KEY });
try {
const page = await gv.pages.get({
workspace: "acme",
id: "page_01H8X4N5P6Q7R8S9T0U1V2W3X4",
});
} catch (e) {
if (e instanceof GavaiError) {
console.error("API error:", e.code, e.message);
if (e.code === "rate_limited") {
// back off and retry — see step 3
} else if (e.code === "token_expired") {
// refresh the token, then retry — see step 2
} else {
throw e; // re-throw anything you do not handle
}
} else {
throw e; // not an API error — propagate as-is
}
}
```
See [SDK error handling](/sdks/error-handling) for the full code list and the properties on `GavaiError`.
Retrying a `not_found` or `insufficient_scope` wastes time and masks configuration bugs. Use this table.
The rule of thumb: retry anything transient and outside your control (`rate_limited`, server errors, network errors). Do not retry anything that needs you to change something first (`token_expired`, `insufficient_scope`, `not_found`, `invalid_input`).
When you do retry, space attempts exponentially and add a small random jitter so clients do not all hammer the API at the same moment after a rate limit clears.
```ts theme={null}
async function withRetry(fn: () => Promise, maxAttempts = 3): Promise {
const delaysMs = [1_000, 5_000, 30_000]; // 1s, 5s, 30s
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
return await fn();
} catch (e) {
if (!(e instanceof GavaiError)) throw e;
const retryable = ["rate_limited"].includes(e.code) || e.status >= 500;
if (!retryable || attempt === maxAttempts - 1) throw e;
const baseMs = delaysMs[attempt] ?? 30_000;
const jitterMs = Math.random() * 1_000; // 0–1s jitter
await new Promise((r) => setTimeout(r, baseMs + jitterMs));
}
}
throw new Error("unreachable");
}
const page = await withRetry(() =>
gv.pages.get({ workspace: "acme", id: "page_01H8X4N5P6Q7R8S9T0U1V2W3X4" })
);
```
Three attempts at roughly 1 s, 5 s, and 30 s gives about 36 seconds of total retry window — enough for a transient rate limit or a brief server hiccup, short enough that a request does not silently block forever.
Before retrying any mutating call, attach an idempotency key. The platform caches the first response for that key for **24 hours**; replays return the original response rather than executing the operation again.
```ts theme={null}
import crypto from "node:crypto";
// Generate the key ONCE, before the first attempt.
// Reuse the same key for every retry of the same operation.
const idempotencyKey = crypto.randomUUID();
const token = await withRetry(() =>
gv.workspaces.tokens.create(
{ workspace: "acme" },
{ name: "ci-token", scopes: ["pages:read"] },
{ idempotencyKey }
)
);
```
The SDK auto-generates an idempotency key for every `POST`, `PATCH`, `PUT`, and `DELETE` call. Pass `{ idempotencyKey }` explicitly when you implement your own retry envelope so the same key is reused across attempts.
See [Idempotency](/api-reference/idempotency) for the cache key construction and the `Idempotent-Replayed: true` response header.
Some operations are dangerous to execute twice.
Double-creating a payment, a member invitation, or an API key can have serious consequences — a customer charged twice, two conflicting invitations to the same email, or a second API key whose secret is unrecoverable (it was returned only in the duplicate response). **Never retry these operations without an idempotency key.** The key is what makes the retry safe.
The three must-attach paths:
`POST /v1/workspaces/{slug}/tokens` — mints a new API key. Each call without a key creates a distinct key.`POST /v1/workspaces/{slug}/members` — creates a new invitation row for each call.Any call to `collectPayment` — opens a new Stripe Checkout session.
Generate the idempotency key before the first attempt and include it on every retry of these calls.
Log the request id on every error so issues are traceable to a specific call. The exact header name is not enumerated in the public source (likely `x-request-id` or similar); confirm with the platform team and pass it to your error tracker alongside `e.code` and `e.message`.
## Troubleshooting
## What you built
You set up typed error catching with `GavaiError`, learned which codes are safe to retry and which require fixing first, implemented exponential backoff with jitter, and attached idempotency keys to writes so retries never cause duplicate side effects. The integration now survives transient failures without double-executing irreversible operations.
## Next steps
Every error code, its HTTP status, and what it means.
How idempotency keys work, which routes require them, and the 24-hour cache window.
GavaiError properties, typed error subclasses, and framework-specific patterns.