If GET, PUT, and DELETE are already idempotent, why do I need idempotency keys?

The HTTP spec describes how those methods are supposed to behave, but the guarantee only exists if your handler implements it, and the operations that hurt most when duplicated, like charging a card or creating an order, are POSTs with no method-level protection. Keys give any operation, regardless of verb, a server-side way to recognize a repeat.

How long should the server remember idempotency keys?

Long enough to cover every realistic retry: client backoff schedules, queue redelivery, and webhook retry windows. Stripe uses 24 hours and that is a good default. Longer retention costs storage and buys protection against ever-rarer late retries; shorter retention risks a late retry being treated as a brand-new operation.

Why not just use a queue with exactly-once delivery instead?

End-to-end exactly-once delivery does not exist in a distributed system, because the acknowledgment itself can be lost, leaving the broker unsure whether you processed the message. Systems that advertise exactly-once semantics, like Kafka transactions, build them from at-least-once delivery plus idempotent processing. That combination is the practical equivalent, and the idempotent half is your job.

Reliabilitychapter 2 of 5 · 3 lessons

Idempotency

Executing the same operation multiple times has the same effect as executing it once.

← All chapters View in cheatsheet

A customer taps pay. The request reaches your server, the card is charged, and the reply is lost on the way back.

Their phone waits 30 seconds, sees nothing, and does what every sensible client does: it tries again. You charge them a second time.

Nothing here is broken. The network dropped one packet, and neither side can tell the difference between a request that never arrived and an answer that never came back.

Retries are everywhere, from mobile clients to queues redelivering to somebody double-clicking a button, and you cannot switch them off. So the second charge has to become impossible instead. An operation is idempotent when running it twice leaves things exactly as running it once would, which is the property that turns every retry above from a threat into background noise.

Lessons

3 in this chapter

Why Retries Need IdempotencyA timeout doesn't tell you whether the operation happened, so every retry is a gamble.2 min
Idempotency KeysThe client names the operation once, so the server recognizes it the second time.2 min
Designing Idempotent OperationsThe cheapest dedup is an operation that is safe to repeat by construction.3 min