Retries are part of ordinary distributed operation. A caller times out before receiving a response, a message becomes visible again, or a worker stops after committing a change. The system must decide whether the next attempt represents the same intention or a new one.
Identity comes before deduplication
An idempotency key is useful only when its meaning is clear. Who creates it? How long is it valid? Can the same key be used with different inputs? Which result should a later caller receive?
Those are domain questions. The storage mechanism comes afterwards.
For an important command, persist the operation identity and its outcome alongside the business change where possible. Reject reuse with conflicting inputs. Return the established result for a genuine repeat.
Exactly once is the wrong conversation
Networks and processes do not offer a magical exactly-once switch. What matters is whether the business effect can be applied more than once.
A message may be delivered repeatedly while its consumer changes a balance once. Conversely, a message recorded once can still trigger duplicate effects when a downstream call is ambiguous. Correctness belongs to the complete workflow, not to the transport label.
Make ambiguity observable
Some outcomes cannot be resolved automatically. Preserve enough context for an operator or reconciliation process to answer what happened: operation identity, attempt history, external references, and the last known state.
Idempotency is successful when retrying becomes safe and ambiguity becomes visible. Treating it as a header alone misses both goals.