Idempotency

Fern supports idempotency configuration through two extensions that work together: x-fern-idempotency-headers configures the idempotency headers your API uses, and x-fern-idempotent marks individual endpoints as idempotent. When configured, Fern’s generated SDKs allow users to specify idempotency headers for safe request retries.

Configure idempotency headers

Add the x-fern-idempotency-headers extension at the root level of your OpenAPI specification to define which headers your API uses for idempotency:

1
x-fern-idempotency-headers:
2
  - header: Idempotency-Key
3
    name: idempotency_key
4
  - header: Idempotency-Expiration
5
    name: idempotency_expiration

Each idempotency header supports the following properties:

Mark endpoints as idempotent

Add the x-fern-idempotent extension to individual endpoints and set it to true to mark them 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
9
      operationId: create_plant
10
      requestBody:
11
        required: true
12
        content:
13
          application/json:
14
            schema:
15
              type: object
16
              properties:
17
                name:
18
                  type: string
19
                species:
20
                  type: string
21
      responses:
22
        '201':
23
          description: Plant created successfully