advanced

Idempotency

Make commands, handlers, and APIs safe to retry by using idempotency keys, natural uniqueness, and explicit duplicate handling.

Retries, at-least-once delivery, and client timeouts make duplicate execution normal. Idempotency ensures repeating the same operation produces the same outcome: idempotency keys on APIs, natural uniqueness constraints, or stored operation results keyed by request ID.

Trade-off: storage for keys and results versus correctness under failure. TTL keys balance memory with retry windows.

On interviews: design a payment API safe under retries; explain key scope (per client, per user) and response replay.

Common pitfalls: idempotency only on HTTP layer without DB uniqueness; keys that collide across operations; deleting keys before retry window ends.

Checklist:

  • Accept Idempotency-Key or equivalent on mutating APIs.
  • Enforce uniqueness at persistence layer.
  • Return same response for duplicate keys.
  • Define key TTL longer than max retry horizon.