Imagine clicking a “Pay Now” button and the network suddenly fails. You don’t know whether the payment was completed, so you try again.
If the server processes both requests independently, the customer could be charged twice.
This is one of the problems that idempotency helps solve. It allows an API to safely receive the same request more than once without performing the same operation multiple times.
What Is Idempotency?
In simple terms, idempotency means:
The same operation can be repeated without creating an unwanted duplicate effect.
For example, if a request creates an order and the same request is accidentally sent twice, an idempotent system should recognize that it is the same operation and avoid creating two orders.
This is especially important for operations involving payments, orders, registrations, and other data-changing requests.
Why Do Duplicate Requests Happen?
Duplicate requests are not always caused by a user clicking a button twice.
They can happen because of:
- Network failures
- Slow API responses
- Automatic retries
- Temporary server problems
- Message queues delivering a message again
- Users refreshing or submitting a form multiple times
One particularly difficult situation occurs when the server successfully processes a request but the response never reaches the client. The client may retry because it cannot tell whether the original request succeeded.
The Problem Without Idempotency
Consider a payment request:
Client → Payment API → Payment Created
But the response is lost:
Client → Payment API → Payment Created → ❌ Response Lost
The client doesn’t know what happened, so it retries:
Client → Payment API → Payment Created Again
Without protection, the same payment could be processed twice.
Using an Idempotency Key
A common solution is an idempotency key.
The client generates a unique key for the operation and sends it with the request.
POST /payments
Idempotency-Key: pay_abc123
The server stores the key along with the result.
The first request:
Key: pay_abc123 → Process Payment → Save Result
If the client retries:
Key: pay_abc123 → Already Processed → Return Previous Result
The payment is not created again.
Simple Example
Imagine an online store.
A customer clicks Place Order.
Order Request
↓
Idempotency Key
↓
API
↓
Check Key
↙ ↘
New Already Used
↓ ↓
Create Return
Order Existing Result
This allows the client to safely retry a request when the result of the first attempt is uncertain.
Where Is Idempotency Useful?
Payments
Payment systems are one of the most important examples. A retry should not accidentally create a second charge. Payment APIs such as Stripe use idempotency keys for this purpose.
Orders
An e-commerce application should not create two orders simply because the customer submitted the same request twice.
Webhooks
Webhook providers may retry event delivery when the receiving application does not respond successfully. The receiving application can use an event ID or another unique identifier to recognize duplicate events.
Background Jobs
A job may be delivered or executed more than once. An idempotency mechanism can prevent the same business operation from being performed repeatedly.
Idempotency and Retries
Retries and idempotency often work together.
Retry without idempotency:
Request → Failure → Retry → Duplicate Operation
Retry with idempotency:
Request → Failure → Retry → Same Key → Safe Result
This makes distributed applications more reliable when network or temporary service failures occur. AWS recommends using idempotency tokens so repeated requests can be recognized and handled safely.
Important Design Considerations
When implementing idempotency, developers should:
- Generate a unique key for each operation.
- Reuse the same key when retrying the same operation.
- Store the key and relevant operation state.
- Return the previous result when the same key is received again.
- Define how long idempotency keys should remain valid.
- Make sure different operations do not accidentally share the same key.
The key should identify the operation, not simply the current time. AWS specifically warns against using timestamps as idempotency keys because they can lead to inaccurate duplicate detection.
Idempotency in Modern APIs
Idempotency is an important reliability pattern for modern applications.
It works particularly well alongside:
API → Retry → Idempotency Key → Database
It can also be combined with webhooks, message queues, payment systems, and microservices to make applications safer when requests or messages are repeated.
Conclusion
Idempotency helps applications handle repeated requests safely.
Instead of assuming that every request happens only once, a reliable system is designed to handle retries and duplicate requests.
The basic idea is simple:
Same Operation + Same Idempotency Key = Same Result
For systems handling payments, orders, webhooks, or other important operations, idempotency can prevent costly duplicate actions and make APIs much more reliable.
