Idempotency & the Exactly-Once Illusion

• The key identifies an intent, not a request. Generated once at intent creation (user taps "buy" → client mints a UUID) and reused across every retry of that intent — client retries, gateway retries, queue redeliveries. A key minted per-attempt dedupes nothing.
• Who mints it: the earliest layer that knows the intent. UI/client for user actions; the producer for events (event ID = idempotency key — your messageId in RabbitMQ headers / Kafka record); the orchestrator for saga steps (M17: sagaId:stepName).
• Scope the key: uniqueness per (key, operation, principal) — the same UUID arriving at a different endpoint or from a different user must not collide. Practically: dedupe store keyed on endpoint + userId + key.
• Same key + different payload = reject (409/422). It signals a client bug or replay tampering; silently returning the stored result for a different request is corruption. Store a payload hash alongside the key and compare.
• Natural keys when they exist: (userId, contentId, billingPeriod) for a subscription charge is better than a UUID — it dedupes across client sessions and even client bugs, because the business itself defines "once".

Fast trackFull read. Every subtlety here is a production bug you'll otherwise meet: the check-then-act race, the in-progress state, the crash-between, the TTL horizon.

• Check-then-act races with itself. Two concurrent duplicates (client retry + gateway retry landing together) both read "no record", both execute. The reservation must be atomic: INSERT ... ON CONFLICT DO NOTHING (winner proceeds, loser reads the record) or Redis SET key state NX. Never SELECT-then-INSERT.
• Three states, not two: IN_PROGRESS → COMPLETED(result) | FAILED. A duplicate arriving during IN_PROGRESS must wait or 409-retry-later — not execute, and not receive a fabricated success. Returning 202/retry-after for in-progress is honest and simple.
• Crash while IN_PROGRESS: the record wedges, blocking the legitimate retry forever. Lease it: IN_PROGRESS carries an expiry; a duplicate after expiry may take over — which is safe only if the underlying operation is itself resumable/idempotent one level down, or reconciled (this is where idempotency meets M19's fencing).
• Atomicity with the business effect: the gold pattern — dedupe record and business write in the same DB transaction (dedupe table in the service's own schema). Redis-based dedupe + DB business-write is two systems, and the crash between them recreates the duplicate (record says done, work isn't) or the loss (work done, record missing → re-execution). Same-transaction or consciously accept the gap.
• Retention = your maximum duplicate horizon: keys must outlive the longest possible redelivery — client retry windows (minutes) < queue redrive from DLQ (days!) < Kafka replay (your retention). 24h–7d typical; partitioned/TTL'd tables keep it cheap. A redrive older than your dedupe TTL is a duplicate generator.
• Store the full first response (status + body), so duplicates receive byte-identical answers — including the original failure: a deterministic business failure (card declined) replays as the same failure rather than re-attempting the charge.

The best dedupe table is the one you don't need. Operations idempotent by construction:

• Absolute over relative: SET resumePoint=1423s replays harmlessly; ADD 10s compounds. State-carrying events over deltas (M15 §04) — the same principle, wire edition. Where deltas are unavoidable (counters), version-guard them: UPDATE ... WHERE version = :expected.
• Upserts with deterministic ids: "create entitlement" as INSERT (userId, contentId, ...) ON CONFLICT (userId, contentId) DO UPDATE — the unique constraint is the idempotency mechanism, enforced by the database with zero extra machinery.
• Version/timestamp guards for LWW updates: apply event only if event.version > row.version — makes consumers tolerant of duplicates and reorder simultaneously (one guard, two M15 problems solved).
• Where it can't be designed away — external side effects: charging a PSP, sending a push, calling the DRM vendor. There you pass your idempotency key downstream (every serious PSP accepts one) and keep the §03 record for the ones that don't.

@Transactional
public PurchaseResult purchase(String key, String userId, PurchaseReq req) {
  int reserved = jdbc.update("""
      INSERT INTO idem (key, user_id, endpoint, payload_hash, state)
      VALUES (?, ?, 'purchase', ?, 'IN_PROGRESS')
      ON CONFLICT (key, user_id, endpoint) DO NOTHING""",
      key, userId, hash(req));

  if (reserved == 0) {                              // duplicate — we lost the race or arrived later
    var rec = idemRepo.find(key, userId, "purchase");
    if (!rec.payloadHash().equals(hash(req)))
      throw new ConflictException("same key, different payload");   // client bug — surface it
    return switch (rec.state()) {
      case COMPLETED   -> rec.storedResult();          // replay the first answer, verbatim
      case FAILED      -> rec.storedResult();          // deterministic failures replay too
      case IN_PROGRESS -> throw new RetryLaterException();  // 202 + Retry-After; never re-execute
    };
  }

  PurchaseResult result = doPurchase(userId, req, key); // key passed to PSP downstream too
  idemRepo.complete(key, userId, "purchase", result);   // SAME transaction as doPurchase's writes:
  return result;                                        // commit is atomic — no gap to crash into
}

Fast trackStep 1 (~30 min): racing your own implementation with concurrent duplicates is the test that matters.

Self-check