Idempotency · OKYC Docs

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.

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.