There’s this kind of bug that doesn’t show up when you’re building.
Everything works.
You click once. It works.
You test your API. It works.
You move on.
Then real users start using it.
Someone clicks “Pay” twice because your page is taking time.
Network glitches and your request gets retried.
A webhook comes in again because you didn’t respond properly the first time.
Now you’re looking at your system like… what just happened?
Two payments.
Duplicate records.
Things just feel… off.
Nothing crashed. But you know something is wrong.
So what is idempotency?
Nothing fancy.
It just means this:
If the same action happens multiple times, the result should still be the same.
Create order → called 3 times → still 1 order
Charge user → called again → still 1 charge
That’s it.
Where most of us get it wrong
When you’re building, you’re thinking:
user will click once
request will go once
job will run once
That’s how we all think at first.
But that’s not how real systems behave.
Browsers retry.
Mobile networks mess up requests.
Background jobs fail and run again.
Payment providers send the same webhook more than once.
Even Stripe literally expects you to handle duplicates. That should already tell you everything.
So the real question is not “will this happen twice?”
It’s “when it happens twice, what does my system do?”
Where this will bite you
Let’s not even overthink it.
Payments
This one is painful.
User clicks twice or request retries → you charge twice.
Now you’re explaining to someone why they were debited two times for something they bought once.
Not fun.
Forms
A Simple form.
User submits twice → you now have duplicate data.
Sometimes you won’t even notice until later.
Webhooks
If you’ve worked with Paystack or anything similar, you already know.
They will send that event again.
If your system treats it like something new every time, you’ll mess up your own data.
Background jobs
This one is sneaky.
Job fails halfway → retries.
If your logic is not careful, it doesn’t “continue”. It repeats.
Now your data is mixed. Some things done twice, some halfway. Good luck debugging that.
The annoying part
These bugs don’t shout.
No big error. No crash.
Just small weird things:
numbers don’t match
users complain randomly
you can’t reproduce it
And you start saying things like:
“it’s working on my side”
Meanwhile, something is clearly wrong.
What actually helps
You don’t need to overcomplicate it.
Just think ahead a bit.
Idempotency keys
For things like payments, send a unique key.
If that same key comes again, don’t process it again. Just return the previous result.
Database constraints
If duplicates should not exist, enforce it at the database level.
Not just “hope your code handles it”.
Check before doing
Before you process something, check:
“has this already been done?”
If yes, stop there.
Assume things will repeat
This mindset alone changes how you build.
Don’t build like things happen once.
Build like things can happen again at any time.
Idempotency is one of those quiet things that makes your system solid.
Conclusion
If your system breaks because the same request happens twice, then it’s not ready.
Simple as that.
Most people only learn this after something goes wrong.
Better to think about it early.
Top comments (0)