How long an idempotency key stays valid
You are storing idempotency keys and need to decide when to delete them.
Twenty-four hours is the common default and it is chosen to outlive any retry a client will attempt. Below roughly one hour, a late retry after a network partition is treated as a new operation and duplicates the work. Above about seven days the table grows without bound for no additional protection, because no client retries a week later.
What the window has to cover
The retention period must exceed the longest interval between a client first attempting an operation and its final retry. For a browser that is seconds. For a mobile client that lost connectivity it can be hours. For a background job with exponential backoff and a long ceiling it can approach a day, which is where the 24-hour convention comes from.
What expiry actually does
Expiry does not undo the original operation. It only removes the server's memory that the key was used, so a retry arriving afterwards is indistinguishable from a fresh request and executes again. The effect is a duplicate created by a cleanup job rather than by the client.
Why unbounded retention is not free
Keys accumulate at the rate of write traffic and are almost never read after the first minute. Retained forever they become the largest table in the system, and any index on them slows the writes that create them.
Where the record should live
The key store has to be reachable by every instance that might receive the retry, which rules out in-process memory the moment there is more than one worker. It also has to survive a deploy, because a client retrying through a rolling restart is exactly the case the key exists for. That usually means the same database as the effect, which has the further advantage of letting the insert share a transaction with it.
Retention windows and what each risks
Retention windows and what each risks
| Window | Covers | Risk |
|---|
| 5 minutes | Immediate retries only | A mobile client back from a tunnel duplicates |
| 1 hour | Most backoff schedules | Long partitions duplicate |
| 24 hours | Effectively every real retry | Standard; table stays bounded |
| 7 days | Nothing extra in practice | Seven times the rows for no gain |
| Forever | Nothing extra | Unbounded growth, slower writes |
Key facts
- Twenty-four hours is the common idempotency key retention window because it outlives every retry schedule a real client uses.
- Expiring a key does not undo the original operation; it removes the record that prevents a later retry from repeating it.
- Retention shorter than about one hour will duplicate work for clients that recover from a network partition and retry.
- Retention beyond roughly seven days adds storage without adding protection, because no client retries a week later.
- A duplicate created after key expiry looks identical to a client bug, which makes the retention setting worth recording next to the endpoint.
Frequently asked questions
What happens if a retry arrives one second after the key expires?
The operation runs a second time. Nothing errors, because from the server's point of view this is a request it has never seen. This is why the window is set from the longest plausible retry interval rather than from storage convenience.
Should the window differ per endpoint?
It can, and it should where retry behaviour differs sharply. A payment submitted from a mobile client deserves a longer window than an internal call between services on the same network.
Can I store keys in a cache rather than a database?
Only if the cache is durable and shared, and most are neither. A cache that is cleared on deploy loses the record precisely when a rolling restart is causing the retries, and a per-instance cache never sees the retry at all if it lands on another node.
Machine-readable copy of this page:
/guide/how-long-to-keep-an-idempotency-key.md