reyhan base

idempotency

2 min read

Definition: Idempotency means that performing the same operation multiple times has the same intended effect as performing it once. (RFC Editor)
It is especially important in APIs because if a request times out, you can retry it without accidentally performing the action twice. (Stripe Docs)

Simple example

Imagine you want to delete user #123:

DELETE /users/123

You send it once → user is deleted.

You accidentally send it 5 times → user is still just deleted, not deleted 5 times.

That’s idempotency.

3 examples

1. Payment

You click Pay €100, but the network times out.

Client → Server
        "Pay €100"
           ↓
       Payment succeeds
           ↓
      Response lost ❌

The client retries the request. With an idempotency key, the server recognizes that this is the same payment and doesn’t charge you twice. Stripe uses this approach for API retries. (Stripe Docs)

Idempotency-Key: abc123

2. Updating a user’s profile

PUT /users/123
 
{
  "name": "Reyhaneh"
}

Send it once → name becomes Reyhaneh.

Send it 10 times → name is still Reyhaneh.

So the operation is idempotent. HTTP defines PUT as an idempotent method. (RFC Editor)

3. Creating an order

Suppose:

POST /orders

creates an order.

If the client sends it twice:

Request 1 → Order #100 created
Request 2 → Order #101 created ❌

That’s not idempotent.

You can make it safely retryable by giving both requests the same idempotency key:

Idempotency-Key: order-abc123
 
Request 1 → Order #100 created
Request 2 → Return Order #100

No duplicate order is created. (Stripe Docs)

Easy way to remember

Idempotent = “I can safely do this again.”

And an important distinction:

Idempotency ≠ “the request only runs once.”

The server may receive the request multiple times; the important part is that repeating it doesn’t produce an additional unintended effect. (RFC Editor)

Database My-Journey-In-Codeless

Graph View