Idempotency Keys

First request performs the effect once; a replay of the same key returns the stored result with no new effect

Idempotency Keys First request performs the effect once; a replay of the same key returns the stored result with no new effect POST (Idempotency-Key: k) lookup k = MISS perform effect once save result under k 200 result POST (same key k) lookup k = HIT 200 stored result (no new effect) First request Replay of same key Client · retries on timeout · Sequence participant Client retries on timeout API server · request handler · Sequence participant API server request handler Idem store · keyed by k · Sequence participant Idem store keyed by k Ledger · the effect · Sequence participant Ledger the effect Legend request return security async trace

First Request

  • • The key k is a MISS in the idempotency store
  • • The effect on the ledger runs exactly once
  • • The result is saved under k before responding

Replay of Same Key

  • • A timeout or retry resends the identical key k
  • • The store returns a HIT and the saved result
  • • The ledger is never touched again

The Point

  • • Idempotency guarantees exactly-once EFFECT
  • • It does not guarantee exactly-once delivery
  • • Clients may retry freely without duplicate effects

Sequence diagram • Built with Archify • Create yours ↗ • Hover to trace • R route • Click to focus • +/− zoom • M radar • [/] views • P play story • T theme • E export