# 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.

From "System design", a free course by Venkat R. Murty: https://designervenkat.online/learn/system-design/idempotent-operations

## 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.

- **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.

```python
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:

```text
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.

## Worked Example: A Pay Button on a Bad Connection

Imagine a shopping app whose checkout screen has a Pay button. A customer taps Pay on a weak mobile signal. The app sends the payment, but the reply times out. The app retries, and without protection the card could be charged twice. Stripe's public API design prevents this with the same key on every attempt. The steps below show how a similar app could use that idea.

1. **Create the key at checkout:** When the customer starts this payment, the app creates a random UUID and stores it with the pending order.
2. **Send the payment with the key:** The app sends the payment request with the key in an Idempotency-Key header, along with the amount and the card token.
3. **Server claims the key:** The server sees a new key, marks it as in progress, and starts the charge.
4. **Reply is lost:** The charge succeeds, but the response is lost on the mobile network. The app sees only a timeout.
5. **App retries with the same key:** The app does not create a new key. It sends the same payment again, with the same amount and the same key.
6. **Server recognizes the repeat:** The server finds the key with a saved result and does not charge the card again. It returns the original success response.
7. **App shows one success:** The app shows 'Payment complete' once. The card has one charge, and the order has one payment record.

```python
saved = {}
charges = []

def pay(key, amount):
    if key in saved:
        return saved[key]
    charges.append(amount)
    result = {'status': 'charged', 'amount': amount, 'number': len(charges)}
    saved[key] = result
    return result

first = pay('key-abc', 25)
retry = pay('key-abc', 25)
other = pay('key-xyz', 40)
print(first == retry)
print(len(charges))
print(other['number'])

```

Output:

```text
True
2
2

```

The sample is a small model of the server. The first call with 'key-abc' charges 25 and saves the result. The retry with the same key returns that saved result and adds no charge. A different key, 'key-xyz', is a new payment, so it is charged. That is why the charge list ends with two entries.

> **Tip:** A real server also compares the amount and other fields with the saved request. If the same key arrives with a different amount, it should return an error, because a reused key with new data is a bug.

## 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?

A. Add a retry limit of three, so the app stops after a few tries.
B. Have the app send a unique key with each new checkout attempt, and have the server save the first result under that key and return it for any repeat.
C. Change the request to GET, because GET is always safe to repeat.
D. Make the timeout longer, so the reply always arrives before the app retries.

**Answer:** B. The key tells the server that a repeat is the same order, so the saved result is returned. A retry limit only caps how many repeats happen. If the first order already succeeded, even one retry can create a copy, and after the limit the app still does not know what happened. GET is wrong, because it should not create orders.

**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?

A. Confirm the message before doing the work, so it is never sent twice.
B. Store the ID of each processed message in the same transaction as the points update, and skip any ID already stored.
C. Ask the broker to stop redelivering messages after one failure.
D. Run the worker on a faster machine, so it finishes before any crash.

**Answer:** B. Storing the message ID with the update lets the worker recognize a repeat and skip it. Confirming first can lose work if the worker crashes before finishing. Stopping redelivery breaks the at-least-once promise, and a faster machine does not remove the crash risk.

**Quick check:** Under the HTTP standard, which statement about request types is correct?

A. POST is idempotent, so retrying a POST never creates a second record.
B. DELETE is idempotent but not safe, because it changes data.
C. GET is idempotent but not safe, because responses can be cached.
D. PUT is safe, because it only replaces data that already exists.

**Answer:** B. DELETE changes data, so it is not safe. Repeating it leaves the same final state, so it is idempotent. POST is not on the idempotent list, GET is safe, and PUT changes data, so it is not safe.

## 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](https://docs.stripe.com/api/idempotent_requests)
- [Stripe docs: Advanced error handling](https://docs.stripe.com/error-low-level)
- [Stripe docs: API v2 overview](https://docs.stripe.com/api-v2-overview)
- [Stripe blog: Designing robust and predictable APIs with idempotency](https://stripe.com/blog/idempotency)
- [RFC 9110: HTTP Semantics (IETF, section 9.2)](https://www.rfc-editor.org/rfc/rfc9110.xml)
- [Idempotency in Distributed Systems: Why It Matters (Hossein Nejati)](https://hosseinnejati.medium.com/idempotency-in-distributed-systems-why-it-matters-41ae6206c9e9)
- [Idempotency and Deduplication in Distributed Systems (Copilot Interview)](https://copilotinterview.com/blog/idempotency-and-deduplication-in-distributed-systems)
- [Idempotency Patterns: Building Retry-Safe Distributed Systems (Backend Bytes)](https://backendbytes.com/articles/idempotency-patterns-distributed-systems/)
- [Idempotency Keys for APIs: How to Implement Them (Easyspawn)](https://easyspawn.com/blog/idempotency-keys)
- [Idempotency Explained: Safe Retries for APIs (Anurag Wagh)](https://anuragwagh.com/blog/idempotency-explained)
- [Idempotent HTTP requests: when a retry is safe (Primusneo guide)](https://primusneo.com/guides/idempotent-requests)
- [Idempotent Receiver Pattern in Distributed Systems (Ajit Singh)](https://singhajit.com/distributed-systems/idempotent-receiver/)
- [Idempotent API (The System Design Newsletter)](https://newsletter.systemdesign.one/p/idempotent-api)
- [Stripe idempotency keys: what they dedupe and how to derive them (Portreeve)](https://portreeve.com/blog/stripe-idempotency-key)
- [Idempotency: What is an Idempotent REST API? (restfulapi.net)](https://restfulapi.net/idempotent-rest-apis/)
