Idempotency key
An idempotent call has the same effect when it repeats. A 10 s lease and 12 s sends made 60 extra emails in the mini board. With the reply ID as an idempotency key, the repeats became safe and no customer got a second reply.
See it on the board
The same traffic runs on two boards. The simulator measured both when this page was built.
| Measure | Goal | No key, retries repeat the effect | Reply ID as the key |
|---|---|---|---|
| Duplicates | none | 60 Fail | 0 Pass |
| Lost writes | none | 0 Pass | 0 Pass |
| Completion time | under 120 s | 92 s Pass | 92 s Pass |
| Monthly cost | 16 USD/mo | 16 USD/mo | |
| p99 latency | 71 ms | 71 ms | |
| Error rate | 0% | 0% |
Key numbers
| Number | Value |
|---|---|
| Email provider call, median | 150 ms |
| Email provider call, p99 | 300 ms |
| Default time a claimed job stays hidden | 30 s |
13 deliveries · 10 payments applied · 0 charged twice
How it works
Networks fail in a way that hides the result. A call times out, and the caller cannot know if the effect happened. The only safe move is to try again. If the effect is not idempotent, such as sending an email, the retry can do it twice.
An idempotency key makes the retry safe. The caller creates a unique ID for each logical action, such as the ID of a support reply, and sends it with every attempt. The receiver stores each key with its result. A second request with the same key does not run the effect again. It returns the stored result.
In the mini board an agent sends support replies through a tool runner. From 0:30 the email service slows down by 6 times, and each send takes 12 s. The queue lease is 10 s, so the queue offers each message to another worker before the first send ends. Both sends finish, and 60 customers get the same reply twice. With the reply ID as the key, the second send is ignored.
Keys need care. Store the key in the same transaction as the effect, or a crash can break the link between them. Keep keys long enough to cover the retry window. And a key must cover the whole action: if the same key is sent with different content, reject it.
In the levels you add keys to the calls that retry and check the count of repeated effects.