> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuahr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry write requests without creating duplicates.

Network calls fail. To let you retry a write safely, the Kua API supports
**idempotency keys** on all unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`)
under `/v1`.

## How it works

Send a unique `Idempotency-Key` header with your request. In the SDKs, pass
`idempotencyKey` / `idempotency_key`:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kuahr.com/v1/employees \
    -X POST \
    -H "X-Api-Key: kua_live_your_key_here" \
    -H "Idempotency-Key: 5f3b9c2a-employee-jane" \
    -H "Content-Type: application/json" \
    -d '{ "firstName": "Jane", "lastName": "Doe", "email": "jane@acme.com", "employmentTypeId": "…", "employedAt": "2026-07-01" }'
  ```

  ```ts Node theme={null}
  await kua.employees.create(
    { firstName: "Jane", lastName: "Doe", email: "jane@acme.com", employmentTypeId: "…", employedAt: "2026-07-01" },
    { idempotencyKey: "5f3b9c2a-employee-jane" },
  );
  ```

  ```python Python theme={null}
  kua.employees.create(
      first_name="Jane", last_name="Doe", email="jane@acme.com",
      employment_type_id="…", employed_at="2026-07-01",
      idempotency_key="5f3b9c2a-employee-jane",
  )
  ```
</CodeGroup>

* The **first** request with a given key is processed and its result stored.
* Any **retry with the same key and the same body** returns the original result
  instead of performing the action again.
* Reusing a key with a **different body** returns `409` — use a fresh key for a
  genuinely different request.

## Choosing a key

Use a value unique to the operation you're performing — a UUID you generate per
attempt, or a natural key like `payroll-run-2026-07`. Keep the same key across
retries of the *same* logical request.

<Tip>
  Idempotency keys are scoped to your company and expire after a retention window.
  Generate a new key for each new operation.
</Tip>