Core concepts
Idempotency
Why every change you make wants a key, and exactly what happens when one repeats.
The problem it solves
Your request times out. You don't know whether it arrived. Retry and you might create a second payroll run. Don't, and you might have created none.
An idempotency key settles it. Send the same key with the same body and you get the original response back, not a second run.
Where it is required
Every POST, PUT, PATCH and DELETE, with two exceptions: registering an account and signing in. GET never needs one, because it changes nothing.
Without one you get missing_idempotency_key, a 400, naming the method and path.
The key is yours to choose. A UUID per attempt is the usual answer. Reuse the same value when you retry the same attempt; a different value is a different request.
What happens on a repeat
| Situation | Answer |
|---|---|
| Same key, same body, first request finished | The original response, with Droomwork-Idempotent-Replay: true |
| Same key, same body, first request still running | conflict, 409. Ask again with the same key |
| Same key, different body | idempotency_key_reused, 409. The key belongs to the first request |
| New key | New work |
Two identical requests racing each other take their turn: one does the work and the other replays it. They never both go through.
Keys are scoped to your organisation, so yours can't collide with anybody else's.