Cianplan

Level 1: Foundations · L1.1 APIs: REST, gRPC, GraphQL, WebSockets/SSE, webhooks

Idempotency keys

Make a POST safe to retry with an idempotency key.

12 min · Free

What you take away

  • A timeout never tells you whether the request was applied, so any retry of a POST risks doing the work twice.
  • The client generates a key before the first attempt and sends the same key on every retry.
  • The server stores the key with the outcome and replays that outcome instead of acting again.
  • The key row must be written in the same transaction as the effect, or a crash in between leaves you with one without the other.

How the class is laid out

  1. The problem
  2. The simple version
  3. What the server does
  4. What this buys, and where the line is
  5. Check your understanding