Retries are inevitable once services talk over networks. Without a shared idempotency convention, the same business event can create duplicate side effects when two teams publish “the same” message with different keys.
Agree on key scope early: which fields identify the business action, how long keys remain meaningful, and where they appear in headers versus payloads. Document what happens when a consumer receives a replay after a partial failure—ack, no-op, or compensate.
Publish the convention in the same place as your API contracts. Integration work gets safer when idempotency is a team agreement, not an individual engineer’s clever header.
