🔁 Anything Can Happen Twice

Make repeated requests safe with idempotency.

FreeData Integrity7 min read

Same request twice → same result once.

What if you tap "Pay" twice by accident?

If you tap Pay twice, you should still be charged once. An idempotency key is like a ticket number: the system sees the same ticket and does not charge again.

💡 Key ideas

The same action repeated should not happen twice
Use a unique key to recognise repeats
Never rely on the button being tapped once

🛠️ How to apply it

Give each important action its own key.
If the key is seen again, return the first result.

Reading level: 🐣 Simple

Networks duplicate. Users double-click. Just accept it.

Any operation that creates, updates, submits, charges or provisions must be evaluated for idempotency. Repeated execution of the same logical operation must not produce duplicate effects.

💡 Key ideas

Use idempotency keys, unique business identifiers and DB uniqueness constraints
Check for an existing operation before processing a new one
Return the original result for a repeat, instead of doing the work again

🛠️ How to apply it

Store the idempotency key with the result; on repeat return the stored result
Add a database uniqueness constraint as the last line of defence

⚠️ Common pitfalls

Generating the idempotency key on the server per attempt, which defeats the whole point

Reading level: 🚀 Standard

Idempotency converts an unsafe operation into a safe one.

An operation is idempotent when applying it more than once has the same effect as applying it once. This lets you retry aggressively, tolerate duplicate delivery, and let clients resend safely.

💡 Key ideas

Scope the key to the operation and the actor (and expiry)
Decide the semantics on key reuse: return cached result vs. 409 conflict
Combine with unique constraints so concurrency cannot slip past the check

🛠️ How to apply it

Persist key → status → result atomically so a concurrent duplicate cannot both proceed
Define expiry to bound storage growth without allowing late duplicates to duplicate

⚠️ Common pitfalls

A read-check-write that races two concurrent duplicates (see Rule 6)
Idempotent at the API but not at the downstream side effect (email still sent twice)

Reading level: 🧠 Deep

Try it yourself

The Double-Tap Pay Button — a live simulator for this principle.

Quick check

Community

Ask a question, share your own analogy, or help someone else get it.