Idempotency Token Store
The durable record of which idempotency keys have been seen and what each one returned, and the component that decides whether the guarantee is real.
The mechanism is trivial to describe and easy to get subtly wrong. What matters is four properties of the store:
Written in the same transaction as the effect. A key recorded separately from the operation can be lost exactly when it is needed — the crash between the two writes is the case idempotency exists to handle.
Storing the response, not just the fact. A retry that returns "already processed" with no body has told the client nothing, so it retries again. Store the status code and payload.
Handling the in-flight case. Two attempts arriving concurrently is the normal case under a retry
storm. Insert the key with an in_progress state under a unique constraint, and return 409 to the
loser so it retries rather than racing.
Bounded retention with a deliberate window. Long enough to outlive any plausible retry — a redelivered queue message, a client retrying after a deployment — which is hours, not minutes. And a TTL, or the table grows forever.
The fifth property is a payload check: the same key with a different request body means the client reused a key, which should be rejected rather than processed.