# Idempotency

> Retry POST requests safely with an Idempotency-Key header.

Source: https://docs.okyc.stream/backend/idempotency

Network errors happen after the API has done the work. Send an `Idempotency-Key` header on `POST` requests and
retry with the same key: you get the original response instead of a second session.

```bash
curl https://api.okyc.stream/v1/sessions \
  -H "Authorization: Bearer $OKYC_SECRET_KEY" \
  -H "Idempotency-Key: signup-user_123-2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{ "workflow_id": "wf_…", "reference_id": "user_123" }'
```

| Situation                                         | Result                                                                    |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| New key                                           | The request runs and its response is stored for 24 hours.                 |
| Same key, same body, same path                    | The stored response, with the header `Idempotent-Replayed: true`.         |
| Same key, different body or path                  | `409`, type `idempotency`, code `idempotency_key_reused`.                 |
| Same key while the first request is still running | `409`, type `idempotency`, code `idempotency_in_progress`. Retry shortly. |
| Key longer than 255 characters                    | `400`, code `invalid_idempotency_key`.                                    |

Choose keys that describe the intent, for example `kyc-<user id>-<date>`, so a double click or a retried job
maps to the same session. Keys are scoped to your account and expire after 24 hours.

`@okyc/node` takes the key per request (`{ idempotencyKey }`). When you don't pass one, it generates a key once
per call and sends it on every `POST`, so its own retries (network errors, `408`, `429`, `5xx`, and
`idempotency_in_progress`) are always safe.