Idempotency

An operation is idempotent if performing it twice has the same effect as performing it once. Setting an order to "shipped" is idempotent. Adding a line to an invoice is not. Charging a card is emphatically not.

This matters because networks fail ambiguously. When a request times out, the caller cannot tell whether it was processed, so the only safe behaviour is to retry — and the only way retrying can be safe is if the operation is idempotent.

The standard implementation is an idempotency key: the caller sends a unique identifier with the request and the server records the outcome against it, so a repeat of the same key returns the original result instead of doing the work again. Any API that moves money or sends messages should have this in its first version, not its third.