Thom's Blog

Idempotency key lock

Failure pattern – Protect against concurrent retries


It is possible for retries to arrive while a previous request is still being processed, for example because the client timed out or crashed. Some operations need protecting against concurrent retries, either to avoid race conditions or to prevent duplicate work.


I can’t think of a problem where concurrency specifically is a problem. If you can, please send me one!


How do we prevent retries from attempting to do work concurrently?


Take a lock on the idempotency key:

  1. Try to acquire a lock on the idempotency key.
  2. If the lock is held, either wait or return an error.
  3. Perform the operation.
  4. Release the lock.

Doing this automatically for every top-level write operation can reduce the cognitive load of needing to think through possible concurrency problems. However, it is often not necessary.


There are often alternatives to locks, especially if correctness if your goal and your storage system supports atomic read-then-write operations, and if operations on other systems are idempotent.

See also