idempotency keys, in practice
A field manual for the engineer who has been bitten once and is now annoyed.
We treat the idempotency key as a first-class object: its anatomy, the failure modes of the obvious schemes, and a recovery procedure for when yours turns out not to have been unique after all. Examples are drawn from production, with the names removed to protect the guilty.
1introduction
Every payment API promises to be safe to retry. Most are — until the afternoon they are not. This paper is about the small object that carries that promise, the idempotency key, and what it costs to take it seriously rather than decoratively.
2anatomy of a key
A key is a client-chosen token that names an intent rather than a request. Two calls bearing the same key are, by contract, the same attempt: the server performs the effect once and returns the same result thereafter, however many times it is asked.
3failure modes
The schemes that fail do so quietly. A key reused across distinct intents merges two payments into one; a key scoped too narrowly splits one into two. Figure 1 traces the path a duplicate must survive without being mistaken for a fresh attempt.
4how often do keys collide?
Keys are only as safe as they are unique. If clients draw n keys uniformly from a space of size N, the probability that two collide follows the familiar birthday bound:
For 128-bit randomness (N = 2128) the term is negligible. For a truncated 32-bit key under real load, it is a Tuesday.
5a recovery procedure
When a key turns out not to have been unique, the remedy is procedural rather than heroic: freeze the key, reconstruct the intended effect from the ledger, and refuse the ambiguous call outright rather than guess. The boring path is the safe one, and it is the only one that survives an audit.