Deep Dives

Configure Idempotency Headers

Pro Feature

This feature is only available on paid plans. Please schedule a demo or email us to get started.

For endpoints you’ve configured as idempotent, Fern’s SDKs allow you to specify idempotency headers. Typically the headers include Idempotency-Key, but you can also specify additional headers.

How it works for SDK users

Your SDK users can specify an idempotency header like this:

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

The generated SDKs will not allow users to specify idempotency headers for non-idempotent endpoints. This is to ensure that the user knows exactly which invocations are idempotent and which are not.

Setting up idempotency headers

To set up idempotency headers in your API, you need to do the following in your overrides file:

  1. Configure the idempotency headers
  2. Mark individual endpoints as idempotent
openapi-overrides.yml
1# Configure the idempotency headers
2x-fern-idempotency-headers:
3  - header: IDEMPOTENCY-KEY
4    name: idempotency_key
5
6# Mark an individual endpoint as idempotent
7paths:
8  /foo:
9    post:
10      x-fern-idempotent: true