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;
Running this once:
user.isActive = true;
or a hundred times:
user.isActive = true;
user.isActive = true;
user.isActive = true;
produces the same outcome.
The user remains active.
This operation is idempotent.
Now compare that with:
user.balance += 100;
Running it once:
Balance = 100
Running it twice:
Balance = 200
Running it three times:
Balance = 300
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);
Looks harmless.
Now imagine this sequence:
Payment Request Sent
↓
Card Charged Successfully
↓
Response Lost Due To Network Failure
↓
Client Retries Request
↓
Card Charged Again
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
Production systems look more like:
Request
↓
Timeout
↓
Retry
↓
Duplicate Request
↓
Partial Failure
↓
More Retries
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
Nothing happens for two seconds.
User clicks again.
Now two requests arrive.
Request A
Create Order
and
Request B
Create Order
If the backend simply executes both:
Order #1001
Order #1002
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
Calling it:
1 Time
10 Times
100 Times
doesn't change the system.
GET is idempotent.
Now consider:
POST /orders
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
Multiple calls:
User A
User B
User C
Potentially multiple records.
Now:
PUT /users/123
Multiple calls:
Update User 123
Update User 123
Update User 123
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
Now your endpoint receives:
Payment Completed
Payment Completed
twice.
If your system isn't idempotent:
Invoice Generated Twice
Email Sent Twice
Inventory Reserved Twice
Chaos follows.
Message Queues Assume Duplicates
Kafka.
RabbitMQ.
SQS.
Azure Service Bus.
Most messaging systems prioritize reliability.
That means:
At Least Once Delivery
instead of:
Exactly Once Delivery
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
Now imagine:
PaymentReceived
arrives twice.
Without idempotency:
Balance += Payment
Balance += Payment
The projection becomes corrupted.
Reliable event processing requires idempotent handlers.
The Idempotency Key Pattern
One of the most common solutions is:
Idempotency Keys
Example:
POST /payments
Idempotency-Key:
abc123
Backend receives:
abc123
and stores:
Request
Result
If the same request arrives again:
abc123
the server returns the previous result instead of executing the operation again.
From the client's perspective:
Retry Safe
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
Now support teams become involved.
With idempotency:
Same Booking
Same Payment
Same Result
No problem.
The retry becomes harmless.
Real World Example: API Studio
Suppose we're building an API testing platform.
User sends:
POST /create-user
five times accidentally.
Should the server create:
5 Users
or:
1 User
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
The problem is that distributed systems make this incredibly expensive.
Instead, many successful systems choose:
At Least Once Delivery
+
Idempotent Consumers
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
Production systems look more like:
Request
↓
Timeout
↓
Retry
↓
Duplicate
↓
Retry
↓
Partial Failure
↓
Retry Again
Once you accept that reality, your design philosophy changes.
You stop asking:
Will This Request Succeed?
and start asking:
What Happens If It Runs Twice?
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)
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.
Top comments (0)