The Retry Problem
Networks drop responses. A client sends a payment, never sees the reply, and retries. Without protection the server could charge twice. An operation is idempotent when running it many times has the same effect as running it once.
Idempotency Keys
For POST writes the client generates a unique idempotency key and sends it with the request. The server records the key with the result. If the same key arrives again, the server returns the stored result instead of doing the work twice.
What the Server Stores
- A mapping from key to the response and status.
- A time window after which keys expire.
- A lock so two concurrent retries do not both execute.
Method Notes
GET, PUT, and DELETE are naturally idempotent by HTTP design. POST is not, which is exactly why payment and order creation endpoints need explicit keys.
Key idea
Idempotency keys let a server detect duplicate writes and return the original result, so retried POSTs never apply the effect twice.