Idempotency

When the API advertises an Idempotency-Key header, the client auto-injects a fresh UUID on each POST. That makes a write safe to retry: the server treats a repeat with the same key as the same operation, so a network blip can’t create two resources.

const client = new Client({ idempotency: true });
await client.pets.createPet({ name: 'Rex' }); // sends a generated Idempotency-Key

This is why the retry policy will retry idempotent mutations but leaves non-idempotent ones alone — the key is what makes the retry safe. Each call gets a fresh key, and that same key is reused across the client’s own retries of that call — so the write applies at most once.

There are two ways an operation becomes idempotent-aware:

• Spec-advertised (automatic). When an operation documents an Idempotency-Key header parameter (or sets x-idempotent: true in the spec), the generator flags that method — it injects the key and is retried even with no client configuration at all. Setting x-idempotent: false opts an operation out. Shipped today in the TypeScript and React Native SDKs; rolling out to the other languages.
• Client-level (idempotency: true). The constructor flag above turns on injection and mutation retries for every mutation, in every SDK — useful when the spec doesn’t document the header but the API supports it.