What is an idempotency key?
An idempotency key is an identifier attached to a request so that a repeat of that request has the same effect as the original. The receiving system recognises the key and returns the result of the first attempt without acting again. It is what makes a retry safe against a system that moves money.
Also called: Idempotency token
Why a retry without a key is simply a second instruction
A payment instruction is sent and the connection drops before the response arrives, so the automation retries. Whether the supplier is paid once or twice now depends entirely on what the receiving system does with that second request. An idempotency key makes the outcome deterministic, which is the difference between a retry policy and a reconciliation exercise. This is the single mechanism most often missing from automations that otherwise look well engineered.
- A retry is indistinguishable from a new instruction without a key tying them together.
- A timeout leaves the caller unable to establish whether the action committed.
- Keys allow aggressive retry policies against systems holding financial state.
- Duplicate detection at the receiver is cheaper than reconciliation afterwards.
How an idempotency key works
- The key is derived from the business identity of the action rather than per attempt.
- It is persisted alongside the task before the request is issued.
- The receiving system stores the key with the result of the first attempt.
- Later requests carrying the same key return that stored result.
- Keys are retained long enough to cover the longest retry or resumption window.
- Systems with no key support are fronted by a ledger of attempted actions.
How an idempotency key is evaluated
Idempotency is proved by deliberately repeating requests rather than by reading an integration document. Measure the following under induced failure:
- duplicate effects produced when a request is repeated
- coverage of keys across every write operation in the workflow
- retention of keys against the longest resumption window
- proportion of keys derived from business identity
- behaviour when the same key arrives with a different payload
Limitations, risks and common failure modes
- Keys generated per attempt defeat the mechanism altogether.
- A receiving system accepts the key field and quietly ignores its meaning.
- Key retention at the receiver is shorter than the sender's retry window.
- The same key is sent with amended content, and the stale result is returned.