# Idempotency

URL: https://softwaredictionary.org/terms/idempotency
Category: Backend & APIs
Last updated: 2026-09-30
Pronunciation: eye-dem-POH-tun-see

In short: Idempotency is the property of an operation that produces the same result whether it runs once or many times, so accidentally repeating a request is safe.

## What is idempotency?

An operation is idempotent if doing it twice, or a hundred times, leaves the system in the same state as doing it once. Setting a user's email to `ada@example.com` is idempotent, because repeating it changes nothing after the first time, while adding $10 to a balance is not, because every repeat adds another $10. A light switch with separate on and off buttons is a good analogy: pressing on twice still just leaves the light on.

Idempotency matters because networks are unreliable. A client may send a payment request, lose the connection before the response arrives, and retry without knowing whether the first attempt succeeded, and message queues and webhooks may deliver the same message more than once. If the operation is idempotent, those retries are harmless instead of charging the customer twice.

In HTTP, methods such as `GET`, `PUT`, and `DELETE` are defined as idempotent, while `POST` is not and `PATCH` is not guaranteed to be. To make `POST` requests safe to retry, many APIs, especially payment APIs, accept an idempotency key: a unique ID the client sends in a header such as `Idempotency-Key`. The server stores each key with its result, so a repeated request with the same key returns the original response instead of running again.

Idempotent does not mean the response is always identical: deleting a resource twice may return `204 No Content` the first time and `404 Not Found` the second, yet the state of the server is the same. Idempotency is also different from being safe, the HTTP term for methods like `GET` that don't change anything at all, so `DELETE` is idempotent but not safe.

## Key takeaways

- An idempotent operation has the same effect no matter how many times it runs.
- It makes retries safe after timeouts, crashes, and duplicate messages.
- `GET`, `PUT`, and `DELETE` are idempotent in HTTP; `POST` is not.
- Idempotency keys let APIs safely retry non-idempotent requests such as payments.
- Responses may differ between calls; what stays the same is the resulting state.

## Example: Handling an idempotency key on the server

```javascript
// Run each payment only once per idempotency key (Express.js)
app.post("/api/payments", async (req, res) => {
  const key = req.get("Idempotency-Key");
  if (!key) return res.status(400).send("Missing Idempotency-Key header");

  const saved = await db.idempotencyKeys.find(key);
  if (saved) return res.status(saved.status).json(saved.body); // replay, don't charge again

  const payment = await chargeCard(req.body);
  await db.idempotencyKeys.save(key, { status: 201, body: payment });
  res.status(201).json(payment);
});
```

## Frequently asked questions

**Which HTTP methods are idempotent?**

`GET`, `HEAD`, `OPTIONS`, `TRACE`, `PUT`, and `DELETE` are idempotent according to the HTTP specification. `POST` is not, and `PATCH` is not guaranteed to be, although a specific API can design them to behave idempotently.

**What is an idempotency key?**

An idempotency key is a unique value, often a UUID, that the client sends with a request, typically in an `Idempotency-Key` header. The server remembers each key and its result, so a retried request with the same key returns the stored response instead of repeating the action.

**What is the difference between safe and idempotent HTTP methods?**

A safe method, such as `GET`, doesn't change data on the server at all. An idempotent method may change data, but repeating it has no further effect, so every safe method is idempotent while `PUT` and `DELETE` are idempotent without being safe.

## Sources

- [RFC 9110: HTTP Semantics, Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2)

---

Software Dictionary: https://softwaredictionary.org/ · https://softwaredictionary.org/llms.txt