Most developers don’t think about idempotency until production breaks.
That’s not because idempotency is an advanced concept. It’s because everything works perfectly when requests succeed exactly once.
Unfortunately, real systems don’t work that way.
Networks fail.
Browsers retry.
Mobile applications reconnect.
Users double-click buttons.
Webhooks arrive multiple times.
Message queues redeliver events.
And suddenly a simple operation that was supposed to happen once happens twice.
Or three times.
Or ten times.
At that moment, one of the most important concepts in software engineering becomes impossible to ignore:
An operation should produce the same result no matter how many times it is executed.
That’s idempotency.
And it’s one of the foundations of reliable software.
What Is Idempotency?
A function is idempotent if performing it multiple times produces the same final result as performing it once.
For example:
user.isActive = true;
Enter fullscreen mode Exit fullscreen mode
Running this once:
user.isActive = true;
Enter fullscreen mode Exit fullscreen mode
or a hundred times:
user.isActive = true;
user.isActive = true;
user.isActive = true;
Enter fullscreen mode Exit fullscreen mode
produces the same outcome.
The user remains active.
This operation is idempotent.
Now compare that with:
user.balance += 100;
Enter fullscreen mode Exit fullscreen mode
Running it once:
Balance = 100
Enter fullscreen mode Exit fullscreen mode
Running it twice:
Balance = 200
Enter fullscreen mode Exit fullscreen mode
Running it three times:
Balance = 300
Enter fullscreen mode Exit fullscreen mode
This operation is not idempotent.
The result changes every time it executes.
Why This Matters More Than Most Developers Realize
Consider a simple payment API.
await chargeCard(order);
Enter fullscreen mode Exit fullscreen mode
Looks harmless.
Now imagine this sequence:
Payment Request Sent
↓
Card Charged Successfully
↓
Response Lost Due To Network Failure
↓
Client Retries Request
↓
Card Charged Again
Enter fullscreen mode Exit fullscreen mode
The payment system behaved correctly.
The network failed.
The client retried.
The customer got charged twice.
The bug isn’t in the payment logic.
The bug is that the operation wasn’t idempotent.
The Reality Of Distributed Systems
Most software developers think in terms of:
Request
↓
Response
↓
Done
Enter fullscreen mode Exit fullscreen mode
Production systems look more like:
Request
↓
Timeout
↓
Retry
↓
Duplicate Request
↓
Partial Failure
↓
More Retries
Enter fullscreen mode Exit fullscreen mode
The moment you have:
- Networks
- APIs
- Queues
- Mobile Apps
- Multiple Servers
you have duplicates.
Not maybe.
Definitely.
The only question is whether your system handles them safely.
The Double-Click Problem
One of the simplest examples.
Imagine an e-commerce checkout page.
User clicks:
Place Order
Enter fullscreen mode Exit fullscreen mode
Nothing happens for two seconds.
User clicks again.
Now two requests arrive.
Request A
Create Order
Enter fullscreen mode Exit fullscreen mode
and
Request B
Create Order
Enter fullscreen mode Exit fullscreen mode
If the backend simply executes both:
Order #1001
Order #1002
Enter fullscreen mode Exit fullscreen mode
The customer now owns two orders.
This happens more often than many developers think.
Why HTTP Introduced Idempotent Methods
HTTP recognized this problem decades ago.
Consider:
GET /users/123
Enter fullscreen mode Exit fullscreen mode
Calling it:
1 Time
10 Times
100 Times
Enter fullscreen mode Exit fullscreen mode
doesn’t change the system.
GET is idempotent.
Now consider:
POST /orders
Enter fullscreen mode Exit fullscreen mode
Every call creates something new.
POST is generally not idempotent.
That’s why retries become dangerous.
PUT Is Often Safer Than POST
Suppose we create a user.
POST:
POST /users
Enter fullscreen mode Exit fullscreen mode
Multiple calls:
User A
User B
User C
Enter fullscreen mode Exit fullscreen mode
Potentially multiple records.
Now:
PUT /users/123
Enter fullscreen mode Exit fullscreen mode
Multiple calls:
Update User 123
Update User 123
Update User 123
Enter fullscreen mode Exit fullscreen mode
Same final state.
This is one reason PUT is considered idempotent.
The Webhook Nightmare
Webhooks are one of the best examples of why idempotency matters.
Stripe.
GitHub.
PayPal.
Most webhook providers explicitly tell you:
Your endpoint must handle duplicate events.
Why?
Because delivery guarantees are difficult.
Imagine:
Payment Completed
↓
Webhook Sent
↓
Server Timeout
↓
Provider Retries
Enter fullscreen mode Exit fullscreen mode
Now your endpoint receives:
Payment Completed
Payment Completed
Enter fullscreen mode Exit fullscreen mode
twice.
If your system isn’t idempotent:
Invoice Generated Twice
Email Sent Twice
Inventory Reserved Twice
Enter fullscreen mode Exit fullscreen mode
Chaos follows.
Message Queues Assume Duplicates
Kafka.
RabbitMQ.
SQS.
Azure Service Bus.
Most messaging systems prioritize reliability.
That means:
At Least Once Delivery
Enter fullscreen mode Exit fullscreen mode
instead of:
Exactly Once Delivery
Enter fullscreen mode Exit fullscreen mode
Because exactly-once delivery is extremely difficult.
The implication is important.
Consumers must be prepared to process duplicate messages.
This is where idempotency becomes essential.
Event Sourcing Depends On It
In a previous article we discussed Event Sourcing.
Imagine an event stream:
OrderCreated
PaymentReceived
InventoryReserved
Enter fullscreen mode Exit fullscreen mode
Now imagine:
PaymentReceived
Enter fullscreen mode Exit fullscreen mode
arrives twice.
Without idempotency:
Balance += Payment
Balance += Payment
Enter fullscreen mode Exit fullscreen mode
The projection becomes corrupted.
Reliable event processing requires idempotent handlers.
The Idempotency Key Pattern
One of the most common solutions is:
Idempotency Keys
Enter fullscreen mode Exit fullscreen mode
Example:
POST /payments
Idempotency-Key:
abc123
Enter fullscreen mode Exit fullscreen mode
Backend receives:
abc123
Enter fullscreen mode Exit fullscreen mode
and stores:
Request
Result
Enter fullscreen mode Exit fullscreen mode
If the same request arrives again:
abc123
Enter fullscreen mode Exit fullscreen mode
the server returns the previous result instead of executing the operation again.
From the client’s perspective:
Retry Safe
Enter fullscreen mode Exit fullscreen mode
This pattern powers many payment systems.
Real World Example: Flight Bookings
Imagine booking a flight.
Customer submits payment.
Network times out.
Browser retries.
Without idempotency:
Two Payments
Two Bookings
Enter fullscreen mode Exit fullscreen mode
Now support teams become involved.
With idempotency:
Same Booking
Same Payment
Same Result
Enter fullscreen mode Exit fullscreen mode
No problem.
The retry becomes harmless.
Real World Example: API Studio
Suppose we’re building an API testing platform.
User sends:
POST /create-user
Enter fullscreen mode Exit fullscreen mode
five times accidentally.
Should the server create:
5 Users
Enter fullscreen mode Exit fullscreen mode
or:
1 User
Enter fullscreen mode Exit fullscreen mode
The answer depends on the business requirement.
Idempotency is not purely technical.
It’s often a business decision.
Why Exactly-Once Is Mostly A Myth
Many developers initially aim for:
Exactly Once Processing
Enter fullscreen mode Exit fullscreen mode
The problem is that distributed systems make this incredibly expensive.
Instead, many successful systems choose:
At Least Once Delivery
+
Idempotent Consumers
Enter fullscreen mode Exit fullscreen mode
This is often simpler and more reliable.
Common Mistakes
Assuming Retries Are Safe
They aren’t.
Retries amplify non-idempotent behavior.
Ignoring Duplicate Webhooks
Every major webhook provider warns about this.
Many developers still forget.
Using Auto-Increment IDs As Deduplication
Duplicates often arrive before the new record is visible.
Trusting The Network
Networks fail constantly.
Design accordingly.
Treating Idempotency As An Optimization
It’s not.
It’s a reliability requirement.
Pros Of Idempotent Systems
1. Safe Retries
Clients can retry without fear.
2. Better Reliability
Transient failures become easier to handle.
3. Simpler Distributed Systems
Duplicate messages stop being catastrophic.
4. Better User Experience
Double-clicks don’t create duplicate operations.
5. More Resilient Event Processing
Replay and recovery become safer.
Cons Of Implementing Idempotency
Let’s be honest.
Idempotency is not free.
1. Additional Storage
Keys and processed requests often need tracking.
2. More Complexity
Deduplication logic must exist somewhere.
3. Edge Cases
Determining whether two requests are truly identical can be difficult.
4. Operational Overhead
Retention and cleanup strategies become necessary.
5. Design Effort
You must think about failures upfront.
The Real Lesson
Most developers think software executes like this:
Request
↓
Success
↓
Done
Enter fullscreen mode Exit fullscreen mode
Production systems look more like:
Request
↓
Timeout
↓
Retry
↓
Duplicate
↓
Retry
↓
Partial Failure
↓
Retry Again
Enter fullscreen mode Exit fullscreen mode
Once you accept that reality, your design philosophy changes.
You stop asking:
Will This Request Succeed?
Enter fullscreen mode Exit fullscreen mode
and start asking:
What Happens If It Runs Twice?
Enter fullscreen mode Exit fullscreen mode
That single question prevents an enormous number of production incidents.
Because in distributed systems, duplicates are inevitable.
Reliable systems aren’t the ones that avoid duplicates.
They’re the ones that make duplicates harmless.
And that’s exactly what idempotency gives you.
What’s Next?
In the next article we’ll discuss:
Why Retry Is One Of The Most Dangerous Keywords In Software
Because once you understand idempotency, you begin to realize something surprising:
retry(3)
Enter fullscreen mode Exit fullscreen mode
might be one of the most dangerous lines of code in your entire system.
About The Author
Hi, I’m Amrish Khan.
I enjoy building developer tools, exploring software architecture, and writing about the deeper ideas behind everyday programming concepts.
I’m also building Aruvix — a growing ecosystem of local-first developer tools designed to process data directly in the browser without unnecessary uploads.
Here’s a detailed blog on Aruvix:
https://dev.to/amrishkhan05/aruvix-the-ultimate-offline-first-developer-toolkit-e0i
You can follow my work and thoughts here:
Portfolio:
https://www.amrishkhan.dev
LinkedIn:
https://www.linkedin.com/in/amrishkhan
GitHub:
https://www.github.com/amrishkhan05
If you enjoyed this article, consider following for more deep dives into JavaScript, architecture, local-first software, and performance engineering.
답글 남기기