We use analytics cookies.We use cookies to analyze site traffic and improve your experience.
Loading...
System Design and AI Engineering, by Roni Das. 984 interactive lessons.
Start LearningFoundation · Core Fundamentals
An operation that produces the same result whether you run it once or multiple times. Critical for safe retries in distributed systems.
In short
Idempotency is the property of an operation that produces the same end result no matter how many times you run it with the same input. Sending a request once or five times leaves the system in the identical state, which is what makes it safe to retry a failed network call without creating duplicate charges, duplicate orders, or corrupted data.
In short
Idempotency is the property of an operation that produces the same end result no matter how many times you run it with the same input. Sending a request once or five times leaves the system in the identical state, which is what makes it safe to retry a failed network call without creating duplicate charges, duplicate orders, or corrupted data.
Learn it in the course
This page is the free part.
₹1,111 in India$25 everywhere elseonce, for the whole course
The System Design course covers Idempotency across a run of lessons, not one page. These 4 alone are about 136 minutes of step-by-step reading, 1 of them with code you run in the browser, all with a quiz.
Why some operations are safe to retry and others charge you twice, and how to make everything safe.
Safely retry failed API requests without causing duplicate side effects.
Design a payment processing system - ACID transactions, idempotency, reconciliation, retry strategies, and the saga pattern for distributed payments.
Detect and discard duplicate messages before they cause double-processing.
all part of
System Design Masterclass
770 lessons · about 287 hours · 18 free to read
₹1,111in India, by UPI
$25everywhere else, by PayPal
It is really nice and good Please join the course
You own this course
Continue with Idempotencypay once,
yours for life
An operation is idempotent if running it twice has the same effect as running it once. Setting a value to 5 is idempotent: assign x = 5 a hundred times and x is still 5. Incrementing a counter is not idempotent: x = x + 1 run three times gives a different result than running it once.
In HTTP this is built into the method semantics. GET, PUT, and DELETE are defined as idempotent. GET reads and changes nothing. PUT replaces a resource with a full representation, so repeating it overwrites with the same data. DELETE removes a resource, and deleting an already-deleted resource leaves the same end state (gone). POST is the odd one out: it is not idempotent, because each POST is meant to create a new resource, so two POSTs create two records.
The word matters because networks are unreliable. A client sends a request, the server processes it, and the response gets lost on the way back. The client cannot tell whether the operation succeeded or failed, so it retries. If the operation is idempotent, the retry is harmless. If it is not, the retry can double-charge a card or place a second order.
Most real systems need to make a non-idempotent operation like a payment safe to retry. The standard technique is an idempotency key: a unique token the client generates (usually a UUID) and sends with the request, often in an HTTP header like Idempotency-Key.
On the first request, the server records the key together with the result of the operation in a store such as Redis or a Postgres table, then returns the response. If the same key arrives again, the server sees it has already processed that key and returns the saved response instead of executing the operation a second time. The charge happens exactly once even if the client retries ten times.
Two details make or break this. First, the lookup and the write must be atomic, usually a database row with a unique constraint on the key, so two concurrent retries cannot both slip through. Second, keys need a time-to-live. Stripe keeps idempotency keys for 24 hours, after which the same key can be reused. The client must generate a fresh key per logical operation, not per retry, so all retries of the same intent share one key.
Use idempotency wherever a retry could cause damage: payment APIs, order placement, sending email or SMS, message consumers reading from a queue, and any write endpoint behind a load balancer or proxy that might re-send on timeout. Message systems like Kafka and SQS deliver at least once, meaning duplicates are expected, so consumers must be idempotent to be correct.
The cost is real but small. You need somewhere to store keys and their results, you pay an extra lookup on every write, and you have to decide on a TTL and a key-generation scheme. Storing the full response so retries get an identical answer adds more storage than just storing a boolean.
The common mistake is assuming a database unique constraint alone gives you idempotency. It prevents duplicate rows, but the client still gets an error on the retry instead of the original success response, which often triggers more retries. True idempotency returns the same successful answer to the duplicate request, not an error.
Stripe is the textbook case. When you create a charge, you pass an Idempotency-Key header with a UUID you generate. If your server times out waiting for Stripe and you retry with the same key, Stripe recognizes it and returns the original charge object rather than charging the customer twice.
Picture an e-commerce checkout. The shopper clicks Pay, the browser sends the request, but the mobile connection drops before the confirmation arrives. The app retries automatically. Without an idempotency key, the customer is charged twice and you get a chargeback and a support ticket. With the key generated once at checkout and reused across retries, the second request is a no-op that returns the same success.
The same pattern shows up everywhere money or side effects are involved. PayPal, Adyen, and most modern payment processors expose idempotency keys, and internal microservices copy the design for their own write endpoints.
Stripe
Accepts an Idempotency-Key header on write requests and stores the result for 24 hours so retried charges return the original response instead of double-charging.
Apache Kafka
Offers an idempotent producer (enable.idempotence=true) that deduplicates retried sends so a record is written exactly once per partition despite retries.
Amazon SQS
Standard queues deliver at least once, so consumers must process messages idempotently; FIFO queues add deduplication IDs within a five-minute window.
PayPal
Its REST APIs support a PayPal-Request-Id header that acts as an idempotency key so retried order and capture calls do not create duplicate transactions.
No. By definition each POST creates a new resource, so sending it twice creates two records. You make POST safe to retry by adding an idempotency key the server uses to detect and ignore duplicates.
A safe method (GET, HEAD) does not modify state at all. An idempotent method may modify state but produces the same end result on repeats. All safe methods are idempotent, but PUT and DELETE are idempotent without being safe because they change data.
Long enough to cover realistic retry windows but not forever. Stripe keeps keys for 24 hours. The store usually has a TTL so old keys expire and the same value can be reused for a new operation later.
Partially. It blocks duplicate rows, but the retry receives a constraint-violation error instead of the original success, which can trigger more retries. Full idempotency means returning the same successful response to the duplicate request, so you usually store and replay the original result.
Systems like Kafka and SQS guarantee at-least-once delivery, meaning the same message can be delivered more than once after a failure or rebalance. If processing the same message twice would double-count or double-send, the consumer must dedupe, typically by tracking a message ID or using an idempotency key.
Idempotency Keys
Safely retry failed API requests without causing duplicate side effects
Design a Payment System
Design a payment processing system - ACID transactions, idempotency, reconciliation, retry strategies, and the saga pattern for distributed payments
Message Deduplication
Detect and discard duplicate messages before they cause double-processing
Idempotent Consumer
Design consumers that produce the same result whether a message is processed once or ten times
Exactly-Once Delivery
The holy grail of messaging, process every message once and only once. Here's why it's nearly impossible and how to fake it.
REST API
An architectural style for building APIs using standard HTTP methods (GET, POST, PUT, DELETE). Resources are identified by URLs.
Retry
Automatically re-attempting a failed operation, usually with exponential backoff. Essential for handling transient failures in distributed systems.
HTTP
The protocol powering the web. A request-response model where clients ask for resources and servers respond. Stateless by design.
Latency
The time delay between sending a request and getting a response. Amazon found every 100ms of extra latency costs 1% in sales.
Throughput
The number of operations a system can handle per unit of time. Think of it as how many cars a highway can move per hour.
Bandwidth
The maximum amount of data that can be transferred over a network in a given time. It's the width of the pipe, not how fast the water flows.
This page explains the idea. The "Idempotency" lesson builds it up step by step, with diagrams. It is part of the System Design Masterclass course, which has 770 lessons. 18 of them are free to read. You pay once and keep it for life, with no subscription.
Open the Idempotency lessoncourse 1
From absolute beginner to principal engineer, drawn step by step.
Asked about Idempotency in an interview?
Each question has why it is asked, a full answer, what the interviewer listens for, the follow-ups, the common mistakes and a diagram (268 diagrams in all). A PDF you keep, junior to staff level.
India: UPI, cards or netbanking through Razorpay. Elsewhere: card or PayPal. Download at once from My packs.
