> For the complete documentation index, see [llms.txt](/llms.txt)

# 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.

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

This is why the [retry policy](/docs/retries) 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.