Idempotency
A network can fail after your request landed but before you saw the answer. If you simply send it again, you might add the same people twice.
An Idempotency-Key makes the retry safe. Submit candidates and Create an interview both require one.
How it works
- Generate a unique key for each logical batch. A random UUID is fine.
- Send it in the
Idempotency-Keyheader. - If you have to retry, send the same key with the same body. Tarkflo returns the original response and creates nothing new. A replayed response carries an
Idempotent-Replayed: trueheader, so you can tell it from a first run.
Keys are remembered for 24 hours. After that, the same key is treated as new.
POST /v1/candidates/submit
Idempotency-Key: 6f0a2d4e-9c1b-4f7a-8e35-1b2d3c4e5f60
Rules
- One key per batch. Never reuse a key for a different batch. Doing so returns
422 idempotency_key_reused. - Store the key with the batch. If your process restarts, you need the same key to retry safely.
- Same body. A retry with a changed body and the same key is an error, not a new request.
- Keys are 1 to 255 printable characters with no spaces.
- A key is scoped to the API key that used it. Two integrations can both use
batch-1. - If a request fails in a way you should simply retry (a
5xx), the key is released, so the retry runs instead of being refused. - If a second request arrives while the first is still running, you get
409 request_in_progress. Wait a moment and retry with the same key. - A request refused up front (an unknown or inactive job, a bad body) is not remembered, so fixing the cause and resending with the same key works.
Idempotency is not deduplication
The key protects one batch from running twice. It does not stop you submitting the same person in two different batches. That case is handled by the job itself: a person who already has an application on the job comes back as already_applied and is not added again.