Notesencoding🌱 seedling

Idempotency

Also: Idempotent · Idempotency Key · Idempotent API · Deduplication · Client Token

An operation is idempotent if doing it several times has the same effect as doing it once. Because a timeout leaves the outcome unknown, idempotency is what makes retries safe; idempotency keys make non-idempotent operations like "charge a card" behave that way.

Why it exists

Clients must retry after timeouts, and brokers redeliver after crashes. Without idempotency every retry risks a duplicate charge, order or email.

How it works

  • Natural idempotency: set a value, delete by ID, upsert by key. Increments, appends and payments are not.
  • Idempotency key: the client generates one unique key per intent (not per attempt) and sends it with every retry.
  • The server stores the key, the request parameters and the response, in the same transaction as the effect, then replays that response for any retry.
  • Same key with different parameters is rejected as a client bug.
  • Keys expire after a retention window; concurrent duplicates are serialized by a lock or unique constraint.
  • Consumers deduplicate the same way, by message ID.

Trade-offs

Gains Costs
retries become safe; duplicates do no harm storage for keys and responses
clear semantics for clients atomicity with the effect is required, or it doesn't work
window limits: a retry after expiry runs again

In practice

  • Stripe accepts an Idempotency-Key on every v1 POST, saves the status and body (even 500s) once execution starts, compares parameters, and may prune keys after 24 hours.
  • AWS EC2 RunInstances takes a ClientToken, stored atomically with the request, kept for the resource's life plus an interval.

Pitfalls

  • Generating the key inside the retry loop: every attempt looks new.
  • Recording the key outside the transaction: a crash leaves a charge without a key, or a key without a charge.

Recall

These cards are also in your review deck, scheduled with spaced repetition.