Idempotent Operations: Making Repeated Requests Safe to Retry
An idempotent operation leaves the system in the same final state no matter how many times it runs, so retries and repeated messages cause no harm.
In short
An idempotent operation leaves the system in the same final state no matter how many times it runs, so retries and repeated messages cause no harm.
15 min readFree
What You Will Learn
Networks are unreliable. A client can send a request, the server can do the work, and then the reply can get lost on the way back. The client cannot tell whether the work happened, so it usually tries again. That retry is useful, but it can also cause harm, such as charging a card twice. This lesson explains idempotent operations, the design property that makes a repeated request safe.
Key words
- Idempotent
- An action is idempotent when doing it once or many times ends with the same final result.
- Side effect
- A change that happens outside the function's own answer, such as a charge, a saved row, or a sent email.
- Retry
- Sending the same request again because the first attempt failed or got no reply.
- Idempotency key
- A unique string the client sends with a request so the server can spot a repeat of that same request.
- At-least-once delivery
- A message system promise that each message arrives one or more times, so duplicates are possible.
- Safe method
- A request type that only reads data and is not meant to change anything.
By the end you will be able to explain why idempotency matters, tell naturally idempotent actions from the rest, add idempotency keys and unique constraints to an operation, and see where the idea shows up in web APIs and message queues.
What Does Idempotent Mean?
An operation is idempotent when running it once and running it many times leave the system in the same final state. The first run may change data. Later runs with the same input should change nothing more. The word comes from mathematics, where applying a rule again to its own result gives the same answer. In software, the goal is simple: a repeat should not add a second effect.
Same final state
After one run or ten runs, the stored data is identical.
No extra side effects
A repeat does not charge the card, create another row, or send another email.
The reply may differ
A second delete might answer 'not found' while the data stays the same. The stored state is what must match.
Idempotency does not stop the first mistake from happening. It makes sure a repeat is not a second mistake. Engineers care because a retry is the normal response to a lost reply.
An operation becomes safe to repeat in one of two ways. Either it is naturally repeatable, or the system is built to recognize repeats. The next two sub-topics show each case.
Which Operations Repeat Safely?
Some actions are safe to repeat by their nature. The action says what the final value should be, not how to change it. If you say 'set the balance to 50', running that twice still leaves 50. The same is true of a full replacement and of a delete by ID.
Set a value
Setting the balance to 50 leaves 50 whether you run it once or three times.
Full replacement with PUT
PUT is a request type that sends the whole new version of a record. Sending it again produces the same record.
Delete by ID
Deleting record 17 removes it once. Later deletes find nothing new to remove.
Which Operations Do Not Repeat Safely?
Other actions describe a change, not a result. 'Add 10 to the balance' is one example, because each run adds 10 more. A POST request, which asks the server to create something new, is another. Each run can create a new record with a new ID. The code below shows both kinds side by side.
balance = 100
def set_balance(value):
global balance
balance = value
return balance
def add_money(amount):
global balance
balance = balance + amount
return balance
print(set_balance(50))
print(set_balance(50))
print(add_money(10))
print(add_money(10))
Output
50 50 60 70
Calling set_balance twice gives 50 both times, so it is idempotent. Calling add_money twice moves the balance from 60 to 70, so a retry changes the result. A safe design turns the second kind into the first kind where possible, or adds a key so the server can tell a repeat from a new request.
Why Do Repeated Requests Happen?
Duplicates are not rare bugs. They are a normal result of how networks and message systems behave. The assumption that a request arrives exactly once breaks in three common ways.
Lost replies
The server finishes the work, but the response never reaches the client. From the client's side, the request simply timed out.
Client retries
Apps, browsers, and SDKs (ready-made code libraries) often retry automatically, so one user action can send the same request twice.
Queue redelivery
A message broker, the system that holds messages for workers, may send a message again if it never receives confirmation that the work was done.
Many teams do not count on exactly-once delivery across a network, so they design receivers that tolerate repeats. The useful goal is an exactly-once effect. The message may arrive twice, but the work is applied once, because the receiver is idempotent.
Tip
When you design an action, ask: 'If this runs twice because the reply was lost, what goes wrong?' If the answer is 'a second charge' or 'a second order', the action needs an idempotency key or a safer design.
How Do You Make an Operation Idempotent?
When an action is not naturally repeatable, you add a mechanism. The main tools are client-made idempotency keys, unique constraints, and conditional updates. Each one lets the server detect or prevent a second copy of the same effect.
Client-Made Idempotency Keys
An idempotency key is a unique string that the client creates for one logical action. The client sends it with every attempt at that action, including retries. Stripe, a payments company, accepts the key in an Idempotency-Key header on its POST requests. It suggests random V4 UUIDs, which are standard random IDs that are practically unique.
- 1
Client makes the key
Before the first attempt, the client creates a random key and keeps it with the pending action.
- 2
Client sends it on every attempt
The first try and every retry carry the same key. A new user action gets a new key.
- 3
Server checks for the key
If the key is new, the server runs the action and stores the key together with the result.
- 4
Server replays the saved result
If the key is already known, the server does not run the action again. It returns the result it saved the first time.
The server must store the response as well as the key. That way a retry gets the same answer the first call produced, even if that answer was an error.
Unique Constraints and Conditional Updates
Keys are not the only tool. Sometimes the data itself can prevent duplicates. A database can refuse a second row with the same value, and an update can succeed only when the record is still in the state the client expects.
Unique constraint
A database rule that says a value, such as an order reference, may appear only once. A second insert with that value fails instead of creating a copy.
Upsert
An upsert means 'insert the row, or update it if it already exists'. Running it again leaves one row with the same contents.
Conditional update with a version
The update says 'change this record only if its version is still 7'. If another change already happened, the update is rejected instead of overwriting it.
The HTTP standard allows conditional requests, which let a client say 'change this only if it still matches what I saw'. The same check helps a retry, because a stale repeat fails safely instead of applying old data again.
How Long to Keep Keys
The server cannot store keys forever. Stripe's documentation says it keeps keys for at least 24 hours before it may remove them. Teams usually choose a window longer than the longest realistic retry period, then clean up old rows with a scheduled job.
Tip
Write the window in your API documentation. Clients need to know how long a retry is safe, and they should never reuse an old key for a genuinely new action.
Two Requests With the Same Key at Once
A retry can arrive while the first request is still running. If the server handles both at once, both may run the action. The server must claim the key before it starts the work, so the second request can see that the first one is in progress. It can then answer with a conflict response, often HTTP status 409, and the caller can try again later.
The same key sent with different data is probably a bug. Stripe rejects a key reused with different parameters, and a server should do the same.
Tip
Make the claim and the business write succeed or fail together, for example in one database transaction, which is a group of changes that either all happen or none do. If the key is marked done only after the work, a crash in between can cause a second run.
Where Idempotency Is Needed
Idempotency matters wherever a request or message can be repeated without the sender knowing whether the first try worked. Three places are most common in system design.
HTTP Method Meanings
HTTP is the protocol that browsers and apps use to talk to servers. Each request has a method, a word such as GET, POST, PUT, or DELETE. That is why a POST that creates an order needs an idempotency key, while a PUT that replaces an order's address does not.
The standard gives the reason for the rule. A client should not retry a non-idempotent request on its own unless it knows the repeat is safe. Idempotent requests can be retried after a failed connection, because the repeat is harmless.
Safe Retries of Failed Calls
A client that gets a timeout cannot know whether the server acted. An idempotent call can be sent again without fear. A non-idempotent call needs a key, or the client must check the server's state first. Stripe's guidance is that a retry with the same key and parameters is safe only within the first 24 hours after the original request.
Tip
Retry only the errors that might have left the work unfinished, such as timeouts. Errors caused by bad input will fail again, so fix the input and then use a new key.
Queue Consumers and At-Least-Once Delivery
A consumer is the part of a system that reads messages from a queue and does the work. Many brokers guarantee at-least-once delivery, so a message may arrive more than once, for example if the consumer crashed before confirming it. The consumer must treat a repeated message as harmless.
A common design stores the ID of each processed message in the same transaction as the work it does. When a duplicate arrives, the consumer sees the ID already stored and skips the work. Because both writes commit together, a crash cannot leave the work done without the record of it, or the reverse.
Idempotent Is Not the Same as Safe
Students often mix up two words. A safe method only reads and is not expected to change anything on the server. An idempotent method may change data, but repeating it adds no further change. The two properties are different, and idempotency is the wider one.
Safe and idempotent
GET and HEAD only read, so they are safe, and repeating them changes nothing.
Idempotent but not safe
PUT and DELETE change data, so they are not safe. Repeating them still leaves the same final state.
Neither by default
POST creates new things with each run, so it is not safe and not idempotent by default. It needs a key to be retried safely.
A delete request shows the difference. It is not safe, because it removes data. It is idempotent, because a second delete removes nothing more.
Common Mistakes
Assuming exactly once
Designs that count on one arrival per request break as soon as a reply is lost. Plan for repeats from the start.
Keying on the wrong thing
A key built from a user's email can clash with that user's other orders. Make each key unique to one logical action.
Marking done too early
If the key is saved as done before the work finishes, a crash can make the server skip work that never happened. Save the result with the work.
Check Your Understanding
Quick check
A mobile app sends POST /orders. The connection times out before the reply arrives, so the app sends the same request again, and the customer sees two identical orders. What change prevents the duplicate, and why would a retry limit alone not fully fix it?
Quick check
A worker reads a message that says 'add 5 bonus points to account 9'. It updates the points, then crashes before confirming the message. The broker sends the message again. Which design keeps account 9 at the correct total?
Quick check
Under the HTTP standard, which statement about request types is correct?
Key Takeaways
Networks drop replies, clients retry, and queues redeliver, so the same request can arrive more than once. An idempotent operation makes that harmless, because the final state is the same after one run or many. Some actions are idempotent by nature, such as setting a value or deleting by ID. Others, such as adding to a balance or creating a record, need an idempotency key, a unique constraint, or a versioned update. Keep the keys, store the results with the work, and remember that idempotent is a different property from safe.
Sources
- Stripe API docs: Idempotent requests
- Stripe docs: Advanced error handling
- Stripe docs: API v2 overview
- Stripe blog: Designing robust and predictable APIs with idempotency
- RFC 9110: HTTP Semantics (IETF, section 9.2)
- Idempotency in Distributed Systems: Why It Matters (Hossein Nejati)
- Idempotency and Deduplication in Distributed Systems (Copilot Interview)
- Idempotency Patterns: Building Retry-Safe Distributed Systems (Backend Bytes)
- Idempotency Keys for APIs: How to Implement Them (Easyspawn)
- Idempotency Explained: Safe Retries for APIs (Anurag Wagh)
- Idempotent HTTP requests: when a retry is safe (Primusneo guide)
- Idempotent Receiver Pattern in Distributed Systems (Ajit Singh)
- Idempotent API (The System Design Newsletter)
- Stripe idempotency keys: what they dedupe and how to derive them (Portreeve)
- Idempotency: What is an Idempotent REST API? (restfulapi.net)
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.