What is idempotency, and how do idempotency keys make retries safe?

Question

IT Interview Practice · Accepted Answer

**Idempotency** means performing an operation **multiple times has the same effect as performing it once**. It matters because networks are unreliable: when a client sends a request and the response never arrives, it can't tell whether the server processed it. If it retries, a non-idempotent operation might run twice.

## The problem

```text
Client ──POST /payments {$100}──▶ Server   (charges $100 ✓)
Client ◀────────X (timeout)────── Server   (response lost)
Client ──POST /payments {$100}──▶ Server   (charges $100 AGAIN ✗ → $200!)
```

`GET`, `PUT`, and `DELETE` are naturally idempotent, so retrying them is safe. `POST` is **not** — this is exactly where duplicate charges and duplicate orders come from.

## The solution: idempotency keys

The client generates a **unique key** (usually a UUID) for the logical operation and sends it in a header. The server stores the key with the result; if the same key arrives again, it returns the **stored** result instead of re-executing.

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Server logic on receiving a request with an Idempotency-Key:
  1. Look up the key in a store (e.g. Redis/DB).
  2. If found → return the saved response (no re-charge).      ← the retry case
  3. If not  → process, save (key → response), then return.
  (Wrap 3 in a transaction / lock so concurrent retries don't double-execute.)
```

The **same key** on retry yields the same `200` and the same payment — the customer is charged once. This is exactly how Stripe's API works.

## Why it matters

This question separates engineers who design for the happy path from those who design for **failure**, which is what production reliability is about. Distributed systems guarantee that timeouts and partial failures *will* happen, so any endpoint with side effects — payments, orders, sending money — needs a retry story, and "just retry" is dangerous for `POST`. The interviewer wants to hear the two-part insight: first, that idempotency is a property you can *design in* (making `PUT`/`DELETE` naturally safe, and giving `POST` an **idempotency key** when it can't be), and second, the subtle concurrency detail — two retries arriving at once must not both execute, so the key check and the write need a lock or unique constraint. Getting this right is the difference between charging a customer once and charging them twice, which is why every serious payments and commerce API implements it.

The problem

The solution: idempotency keys

Why it matters

Related questions