Skip to main content
Attach an Idempotency-Key header to any write request and the server will return the cached response on a retry instead of executing the operation a second time. This is how you guard against duplicate side effects from network failure, browser double-submit, or dispatcher re-delivery. By the end of this page you will know what the key is, when to send it, and the rules the cache enforces.

​
How it works

​
Where it applies

Method classBehavior
GETNaturally idempotent. Header is ignored if sent.
POST, PUT, PATCH, DELETEHeader is honored. Cached responses are replayed inside the 24-hour window.
Writes that create new resources — minting API tokens, sending invitations, attaching domains — should always carry a key. Without one, a retry creates a second resource.

​
Key requirements

​
Cache window

The cached response lives 24 hours from the first successful request. After that, the entry expires and the same key is treated as a new attempt. The window covers dispatcher retries, CI re-runs, and same-day human double-submits. The cache is eventually consistent across regions — propagation is typically under 60 seconds. A retry hitting a different region inside that window may execute again. For payment-class operations, treat idempotency keys as necessary but not sufficient and combine with application-level deduplication.

​
TypeScript SDK

@gavai/sdk-typescript generates and attaches an Idempotency-Key for every POST, PATCH, PUT, and DELETE call. Pass { idempotencyKey } explicitly when you need to control the key across a retry loop: 
import { GavaiClient } from "@gavai/sdk-typescript";

const client = new GavaiClient(process.env.GAVAI_API_KEY!);

const key = crypto.randomUUID();

// Both calls carry the same key — only one token is minted.
const token = await client.workspaces.tokens.create("acme",
  { scopes: ["pages:read"] }, { idempotencyKey: key });

const same  = await client.workspaces.tokens.create("acme",
  { scopes: ["pages:read"] }, { idempotencyKey: key });

// same.id === token.id — the second call returned the cached response.

​
Next

Errors and retries

Status codes, retry classes, and the Retry-After contract on 429s.