> This page is for SDKs, version Legacy.
> For other versions, use one of these documentation indexes:
> - Current (default): https://buildwithfern.com/learn/sdks/current/llms.txt
> - Legacy: https://buildwithfern.com/learn/sdks/legacy/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Configure idempotency headers

> Configure idempotency headers for SDKs that support retrying requests

> **You're viewing the legacy SDK docs**
>
> These pages cover SDK generation configured with `generators.yml`. New projects use `sdk-config.yml`, so see [the Current version of this page](/learn/sdks/deep-dives/idempotency) for up-to-date guidance. To move an existing project, follow the [SDK Config migration guide](/learn/sdks/legacy/generators/migration-guides/sdk-config), which walks through `fern sdk migrate`, and review the [`sdk-config.yml` reference](/learn/sdks/reference/sdk-config).

For endpoints you've configured as idempotent, Fern's SDKs allow users to
specify idempotency headers for safe request retries. Typically the headers include `Idempotency-Key`,
but you can also specify additional headers.

## Generated SDK behavior

The generated SDKs expose idempotency headers as parameters only for endpoints marked as idempotent, ensuring users know exactly which invocations are idempotent.

#### TypeScript

```ts {5}
const response = await client.transactions.send({
  amount: 100,
  currency: "usd",
}, {
  idempotencyKey: "64099353-b48b-4dcd-98b7-74df1cc57933"
});
```

#### Python

```python {4}
response = client.transactions.send(
  amount=100, 
  currency="USD", {
  idempotency_key="64099353-b48b-4dcd-98b7-74df1cc57933"
})
```

#### Java

```java {7}
var response = client.transactions().send(
  SendTransactionsRequest.builder()
    .amount(100)
    .currency(Currency.USD)
    .build(),
  IdempotentRequestOptions.builder()
    .idempotencyKey("64099353-b48b-4dcd-98b7-74df1cc57933")
    .build()
);
```

#### Go

```go {7}
response, err := client.Transactions.Send(
  ctx,
  &SendTransactionsRequest{
    Amount: 100,
    Currency: Currency.USD,
  },
  option.WithIdempotencyKey("64099353-b48b-4dcd-98b7-74df1cc57933"),
)
```

## Auto-generate idempotency keys

Generated SDKs can attach an idempotency-key header automatically, generating a UUIDv4 value for each request unless the caller supplies one. Enable it once for every generator under [`api.settings`](/learn/sdks/legacy/reference/generators-yml#settings):

**`generators.yml`**

```yaml title="generators.yml"
api:
  settings:
    auto-generate-idempotency-key: true
```

By default the SDK sends an `Idempotency-Key` header on `POST` and `PUT` requests. Pass an object to change the header name or the eligible methods:

**`generators.yml`**

```yaml title="generators.yml"
api:
  settings:
    auto-generate-idempotency-key:
      header-name: X-Idempotency-Key
      methods:
        - POST
        - PUT
        - PATCH
```

To override the API-level value for a single SDK, set `auto-generate-idempotency-key` under that generator's `config`. Auto-generation is supported by the [TypeScript](/learn/sdks/legacy/generators/typescript/configuration), [Python](/learn/sdks/legacy/generators/python/configuration), [Java](/learn/sdks/legacy/generators/java/configuration), [Go](/learn/sdks/legacy/generators/go/configuration), [C#](/learn/sdks/legacy/generators/csharp/configuration), [PHP](/learn/sdks/legacy/generators/php/configuration), and [Ruby](/learn/sdks/legacy/generators/ruby/configuration) SDKs.

## Setting up idempotency headers

Configure the idempotency headers your API uses, then mark individual endpoints as idempotent:

**`openapi.yml`**

```yaml title="openapi.yml" {2-4,10}
x-fern-idempotency-headers:
  - header: IDEMPOTENCY-KEY
    name: idempotency_key

paths:
  /plants:
    post:
      x-fern-idempotent: true
```

For full configuration details, see [Idempotency in OpenAPI](/learn/api-definitions/openapi/extensions/idempotency).