Idempotency - Kua API

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:

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": "[email protected]", "employmentTypeId": "…", "employedAt": "2026-07-01" }'

await kua.employees.create(
  { firstName: "Jane", lastName: "Doe", email: "[email protected]", employmentTypeId: "…", employedAt: "2026-07-01" },
  { idempotencyKey: "5f3b9c2a-employee-jane" },
);

kua.employees.create(
    first_name="Jane", last_name="Doe", email="[email protected]",
    employment_type_id="…", employed_at="2026-07-01",
    idempotency_key="5f3b9c2a-employee-jane",
)

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.

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

​How it works

​Choosing a key

How it works

Choosing a key