Idempotency

Send an Idempotency-Key header (1 to 255 characters, kept 24 hours) on a write, and a retry of the same request returns the original response instead of applying it twice. If a write times out, you cannot tell whether it happened, so this is how you retry safely.

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/people \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: 6f1c2a4e-create-john-smith" \
  -H "Content-Type: application/json" \
  -d '{"given_name": "John", "surname": "Smith"}'

Use any unique string of 1 to 255 characters, such as a UUID. A key outside that range returns 422 validation_failed.

What happens on a retry

Keys are kept for 24 hours.

• Same key, same request: you get the original response again, including the original body and its original request_id. The write is not repeated. Other headers are not replayed, but a replay carries Idempotent-Replayed: true so you can tell.
• Same key, different request: 409 conflict. A key belongs to one request.
• Same key while the first request is still running: 409 conflict. Wait and retry. If the first request never finished (for example, our server restarted mid-request), the key stops blocking after 30 minutes and the retry runs.

Which responses are stored

• A success, or an error that means the request was understood and refused for good (for example 404 or 403), is stored and replayed.
• 402, 409 and 429 responses and 422 validation_failed do not use up the key: nothing changed, so retry with the same key once the cause is fixed. For example, buy credits after a 402, wait for Retry-After after a 429, or wait for the record to finish processing after a 409.
• A 5xx releases the key, so a retry runs again.

Where it applies

All write endpoints honor Idempotency-Key, with one exception:

• Uploads are not idempotent. Retrying POST /records creates another record, and retrying POST /gedcom/imports uploads the file again. See Uploads and GEDCOM import and export.

Without a key, a retry of some writes will fail on its own. For example, confirming a record twice returns 409 because it is already confirmed.