Notesencoding🌱 seedling
Idempotency
Also: Idempotent · Idempotency Key · Idempotent API · Deduplication · Client Token
An operation is idempotent if doing it several times has the same effect as doing it once. Because a timeout leaves the outcome unknown, idempotency is what makes retries safe; idempotency keys make non-idempotent operations like "charge a card" behave that way.
Why it exists
Clients must retry after timeouts, and brokers redeliver after crashes. Without idempotency every retry risks a duplicate charge, order or email.
How it works
- Natural idempotency: set a value, delete by ID, upsert by key. Increments, appends and payments are not.
- Idempotency key: the client generates one unique key per intent (not per attempt) and sends it with every retry.
- The server stores the key, the request parameters and the response, in the same transaction as the effect, then replays that response for any retry.
- Same key with different parameters is rejected as a client bug.
- Keys expire after a retention window; concurrent duplicates are serialized by a lock or unique constraint.
- Consumers deduplicate the same way, by message ID.
Trade-offs
| Gains | Costs |
|---|---|
| retries become safe; duplicates do no harm | storage for keys and responses |
| clear semantics for clients | atomicity with the effect is required, or it doesn't work |
| window limits: a retry after expiry runs again |
In practice
- Stripe accepts an Idempotency-Key on every v1 POST, saves the status and body (even 500s) once execution starts, compares parameters, and may prune keys after 24 hours.
- AWS EC2
RunInstancestakes aClientToken, stored atomically with the request, kept for the resource's life plus an interval.
Pitfalls
- Generating the key inside the retry loop: every attempt looks new.
- Recording the key outside the transaction: a crash leaves a charge without a key, or a key without a charge.
Connections
- Part of
- Encoding
Recall
These cards are also in your review deck, scheduled with spaced repetition.