Cross-post. Original: stellarbytecapital.com/blog/idempotent-api-design
Somewhere between your client and your server, a request will time out after the work was done but before the response came back. The client, seeing no answer, retries — and now you've charged the card twice, created two orders, or sent two transfers. Idempotency is the property that makes a retry safe: doing the same operation twice has the same effect as doing it once. For anything that moves money or creates records, it's not optional.
What "idempotent" really means here
GET, PUT, and DELETE are naturally idempotent — repeatable without additional effect. The problem is POST ("create a charge," "place an order"), which is not. Each call is meant to do something new, so a blind retry does the thing again. Idempotency keys make those unsafe POSTs safe to retry.
Idempotency isn't about the network never failing. It's about the operation staying correct when the network fails and the client retries — which it will.
