Idempotency Keys in API Design

In distributed networks, communication between clients and servers is fundamentally unreliable (The Two Generals Problem).

The Double-Charge Disaster:

1. A mobile client sends POST /v1/charges to purchase a $500 flight ticket.
2. The server receives the request, deducts money from the bank account, and commits the transaction.
3. As the server sends 200 OK back to the client, the client's mobile cellular connection drops.
4. The client encounters a network timeout. Not knowing if the charge succeeded, the client's automated retry logic re-sends the exact same POST /v1/charges request.
5. Without Idempotency: The server charges the customer a second time ($1,000 total) and creates duplicate flight reservations!

What is Idempotency?

An operation is idempotent if applying it multiple times produces the exact same server state as applying it once:

f(f(x)) = f(x)

While HTTP GET, PUT, and DELETE are idempotent by specification, HTTP POST is non-idempotent. Idempotency Keys make POST mutations safe to retry indefinitely.