Configure idempotency headers

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.

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

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:

1
api:
2
  settings:
3
    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:

1
api:
2
  settings:
3
    auto-generate-idempotency-key:
4
      header-name: X-Idempotency-Key
5
      methods:
6
        - POST
7
        - PUT
8
        - 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, Python, Java, Go, C#, PHP, and Ruby SDKs.

Setting up idempotency headers

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

1
x-fern-idempotency-headers:
2
  - header: IDEMPOTENCY-KEY
3
    name: idempotency_key
4
5
paths:
6
  /plants:
7
    post:
8
      x-fern-idempotent: true

For full configuration details, see Idempotency in OpenAPI.