How Idempotency Works
IntermediateAn operation is idempotent if doing it multiple times has the same effect as doing it once. This matters because networks are unreliable: a client may time out and retry a request that actually succeeded, causing a duplicate charge or order. Idempotency makes retries safe. Some HTTP methods (GET, PUT, DELETE) are naturally idempotent; POST is not, so APIs use an idempotency key to detect and collapse duplicate requests.
Think of an elevator call button
Pressing the elevator button once calls the elevator. Pressing it five more times does nothing extra — the elevator still comes once. That is idempotency: repeated presses have the same result as one. A non-idempotent action would be like each press adding another elevator to your order. Payments must behave like the button, not like ordering extra elevators, so a client that nervously retries never gets charged twice.
Step by Step
Key Concepts
Idempotency Key
A unique client-generated identifier sent with a request. The server uses it to detect duplicates: the same key means the same logical operation, so it returns the original result instead of repeating the action.
Idempotent HTTP Methods
GET, PUT, and DELETE are idempotent by definition — repeating them yields the same state. POST is not, which is why create operations need idempotency keys to be safely retryable.
At-least-once vs Exactly-once
Reliable delivery usually guarantees at-least-once (possible duplicates). Idempotency on the receiver turns at-least-once delivery into effectively exactly-once processing.
Deduplication Window
How long the server remembers idempotency keys. Keys are typically stored with an expiry, balancing duplicate protection against storage — long enough to cover realistic retry windows.
Key Facts
- Idempotency is the practical way to get exactly-once effects on top of unreliable, at-least-once networks and message queues.
- Payment APIs like Stripe require an Idempotency-Key header on charge requests precisely to prevent double charges from retries.
- The key must be stored atomically with the result — a race between two concurrent duplicates can double-process if the check and write are not atomic.
Real-World Applications
Payment processing
A checkout sends a charge with an idempotency key. If the app times out and retries, the payment provider recognises the key and returns the original charge — the customer is billed exactly once.
Message queue consumers
Queues deliver at-least-once, so a consumer may see a message twice. Making the handler idempotent (dedup by message ID) ensures reprocessing a duplicate does not create duplicate orders or emails.
Frequently Asked Questions
What does it mean for an operation to be idempotent?
It means performing the operation multiple times has the same effect as performing it once. Setting a value, deleting a resource, or reading data are idempotent — repeating them does not change the outcome. Creating a new charge or order is not, unless you add protection like an idempotency key.
How does an idempotency key prevent duplicate charges?
The client sends a unique key with the request. The server records that key alongside the result before responding. If the client retries with the same key, the server recognises it as a duplicate and returns the stored result instead of charging again — so retries are safe and the customer is billed once.
Which HTTP methods are idempotent?
GET, PUT, and DELETE are idempotent by definition: repeating them leaves the system in the same state. POST is not idempotent because each call can create a new resource — which is why create endpoints use idempotency keys to make them safely retryable.
How is idempotency related to exactly-once processing?
Truly exactly-once delivery is very hard over unreliable networks, so systems usually guarantee at-least-once, meaning duplicates can occur. Making the receiver idempotent — deduplicating by key or message ID — turns at-least-once delivery into effectively exactly-once processing, which is the pragmatic solution.