What Is Idempotency?

Idempotency means that performing the same operation multiple times results in the same outcome. That is, no side effects beyond the first execution.

Think of it like a doorbell: Tap once, tap ten times The bell rings. It doesn’t install a new bell each time.

In APIs:

• GET /users/123 is naturally idempotent — you get the same user every time.

• DELETE /orders/10 should be idempotent — delete is delete, even if the client calls it twice.

• POST /payments is not idempotent by default — multiple POSTs might create multiple charges.

To make non-idempotent actions safe, we introduce Idempotency Keys.

What Are Idempotency Keys?

An idempotency key is a unique token generated by the client and included with an API request (usually in a header). The server stores the result of the first request associated with that key.

If the same key appears again, the server returns the original response instead of executing the action again. Example:

POST /checkout
Idempotency-Key: 7f1c21fa-f772-4ef5-9b5a-0fb83adb19b5

If the client retries the exact same request with the same key:

How Idempotency Keys Work on the Backend (High-Level)

Idempotency key enforcement strategies

1. Strict Enforcement:

The server can make idempotency keys compulsory for some requests, by setting the idempotency_key request header as required, just like requiring an Authorization header.

app.post("/book-seat", async (req, res) => {
  const key = req.header("Idempotency-Key");
  if (!key) {
    return res.status(400).json({
      error: "Missing Idempotency-Key header"
    });
  }
  // proceed with idempotency logic...
});

2. Optional Enforcement:

The API can accept requests without a key, but this configuration results in non-idempotent behavior.

In some APIs, idempotency is optional.

Clients that want safety include a key. Clients that don’t → take the risk.

This is typical in internal services where you fully control both client and server code.

What causes request retries?

Handling Retries Safely on the Frontend

Even with backend idempotency, your frontend should also help reduce unnecessary repeated calls.

Use Idempotency Keys for Non-Idempotent Actions.

The frontend should generate a unique key before sending requests for:

import { v4 as uuid } from "uuid";

async function createOrder(cart) {
  const key = uuid();
  const res = await fetch("/api/checkout", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify(cart),
  });
  return res.json();
}

Disable UI Buttons During In-Flight Requests

<button disabled={loading}>
  {loading ? "Processing..." : "Checkout"}
</button>

Detect Duplicate Submissions in the UI

If the user refreshes mid-checkout, store the idempotency key in:

localStorage, or

React Query’s cache

So if they retry, they reuse the same key.

Putting It All Together: A Safe Flow

Final Thoughts