Skip to main content

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​

  1. Generate a unique key for each logical batch. A random UUID is fine.
  2. Send it in the Idempotency-Key header.
  3. 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: true header, 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.