Idempotency (Deep Workflow)

Most distributed systems deliver work at least once. Idempotency makes duplicate processing safe—critical for payments, inventory, and message consumers.

When to Offer This Workflow

Trigger conditions:

• Retries on HTTP, queues, or background jobs
• Double charges, duplicate records, or “at-least-once” confusion
• Product asks for “exactly-once” semantics

Initial offer:

Use six stages: (1) identify side effects, (2) choose keys, (3) storage & scope, (4) API patterns, (5) worker patterns, (6) testing). Confirm storage (Redis, SQL) and retention window.

Stage 1: Identify Side Effects

Goal: Classify operations: reads vs creates vs monetary transfers vs state transitions.

Exit condition: List of mutations that must be idempotent under retries.

Stage 2: Choose Keys

Goal: Client-supplied Idempotency-Key header (Stripe-style) vs deterministic hash of normalized payload—trade UX vs collision risk.

Stage 3: Storage & Scope

Goal: Store key → outcome or result reference with TTL covering retry window; scope keys per tenant/user when needed.

Stage 4: API Patterns

Goal: Same key + same body → same outcome; reject or conflict if same key with different body.

Stage 5: Worker Patterns

Goal: Natural unique constraints in DB; dedupe table keyed by event_id or business idempotency key for consumers.

Stage 6: Testing

Goal: Chaos or integration tests that deliver duplicate messages; property tests for key behavior.

Final Review Checklist

• [ ] Mutating paths classified
• [ ] Key strategy and scope documented
• [ ] Storage, TTL, conflict rules defined
• [ ] HTTP and async consumers aligned
• [ ] Duplicate delivery tests

Tips for Effective Guidance

• True exactly-once end-to-end is rare—design for at-least-once + idempotent effects.
• Pair with message-queues and rest-best-practices for HTTP idempotency keys.

Handling Deviations

• Financial flows: require stronger audit and longer key retention.