Idempotent Receiver

Overview

An idempotent receiver ensures that processing the same request twice has the same outcome as processing it once. It is the standard defence against the duplicates that retries and at-least-once delivery inevitably produce.

How it works

The client generates a unique key per logical operation and reuses it on every retry. The server records the key with the outcome.

POST /payments
Idempotency-Key: 7f3a-91c2

BEGIN;
  INSERT INTO idempotency(key, request_hash) VALUES ('7f3a-91c2', 'h1')
    -- unique constraint; conflict means duplicate
  perform charge, store response
COMMIT;

If the insert conflicts, the server loads the stored response and returns it. If the key exists with a different request hash, it returns 422. For message consumers, the key is the message id, and the dedup record is written in the same database transaction as the state change, so a crash cannot separate them.

Pitfalls

• Check-then-act races. Use a unique constraint or lock, not a plain read followed by an insert.
• Storing the key outside the effect transaction, which loses atomicity when calling external systems; pass the key downstream too.
• Short retention. Keep keys longer than the longest retry or redelivery window.
• Server-generated keys. The client must create the key, otherwise retries get new ones.
• In-flight duplicates. Return a conflict or wait while the first attempt is still processing.

Key takeaways

• Client supplies a stable key; server stores key and result atomically.
• Use unique constraints to resolve concurrent duplicates.
• Retain keys beyond the retry horizon and validate payload equality.