Idempotency

A Retry Must Not Corrupt State

In a distributed system, you cannot assume that every request or message arrives exactly once. A client can retry a request after a timeout, and a broker can redeliver a message if it did not receive processing acknowledgement.

An idempotent operation allows the same logical request to be repeated without an additional state change. For example, setting an order status to CANCELLED again is usually safer than executing the command "charge 500 rubles" twice.

An Idempotency Key Distinguishes a Retry from a New Operation

For creation or payment operations, a client can send a unique key. The service stores the result of the first execution and returns it again for a retry with the same key, without performing the business action a second time.

POST /payments
Idempotency-Key: 8f76c0d2-...

{
  "orderId": 421,
  "amount": 500
}

The key must belong to one logical operation and be stored long enough to cover the real window in which retries can occur.

Message Consumers Must Account for Duplicates Too

A message can carry a stable eventId. Before performing an irreversible action, a consumer can check whether that identifier has already been processed, and then store the successful-processing fact together with the business change as atomically as the chosen storage allows.

eventId = evt-42

first delivery  -> process -> remember evt-42
second delivery -> already processed -> skip

Repeating a Response and Repeating an Effect Are Different Things

An operation may return the same successful result again, but the main goal is to avoid repeating a dangerous side effect: do not charge money again, do not create a second order, and do not award a bonus twice. That is what makes retries safe for a distributed system.