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:

x-fern-idempotency-headers:
  - header: Idempotency-Key
    name: idempotency_key
  - header: Idempotency-Expiration
    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. A marked operation also exposes an --idempotency-key flag in a generated CLI and becomes eligible for automatic retries:

x-fern-idempotency-headers:
  - header: Idempotency-Key
    name: idempotency_key
paths:
  /plants:
    post:
      x-fern-idempotent: true
      operationId: create_plant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                species:
                  type: string
      responses:
        '201':
          description: Plant created successfully