Retrying safely
Idempotency keys, and what happens when you reuse one.
Every endpoint that creates something accepts an idempotency key:
POST /api/v1/credentials
Idempotency-Key: 7f3c1e2a-...
Retry with the same key and you get the original response back, with Idempotent-Replay: true.
Nothing is created twice.
The body is fingerprinted too
Reusing a key with a different body is refused with IDEMPOTENCY_KEY_REUSED rather than
replayed. Replaying would answer a question nobody asked: you would receive the result of the
first request while believing you had made the second.
While the first one is still running
A retry that arrives before the original has finished gets IDEMPOTENT_REQUEST_IN_PROGRESS. That is
a correct and retryable answer — wait and try again.
If the process handling the original dies, its claim is released after two minutes, and a retry after that is treated as a new request. The dead attempt never created anything, so the retry is not a reuse of the key.
The window
24 hours. After that a key is forgotten and may be used again.