← All writing

Designing idempotent APIs

Why retries are inevitable, and how to make endpoints safe to call more than once.

Retries are not an edge case. Timeouts, dropped connections and client bugs all cause the same request to arrive twice. An API that assumes exactly-once delivery will eventually corrupt data.

The usual fix is an idempotency key: the client generates a unique value, the server stores the first result against it, and repeats return that stored result. The important part is storing the result, not just recognizing the key.

Pair that with clear status codes and short-lived keys, and your endpoints become boring in the best possible way.