liveBook · Manning

Idempotency key

As explained in Crack Any Codebase with AI

An idempotency key is a value that identifies logically identical operations so repeated attempts can be detected and prevented from creating duplicate effects.

An idempotency key identifies one logical operation across repeated attempts. When a client double-clicks Confirm or retries a stalled POST, the server recognizes the repeat and returns the existing result instead of creating another effect. section 8.5

The key is usually protected by a database UNIQUE constraint. In the booking flow, the server deterministically hashes startTime, endTime, and userId into a uuidv5. Identical requests calculate the same key; the first insert succeeds, while the second is converted into a response for the existing booking. section 8.5

One booking from two Confirm clicks

Two requests arrive with the same idempotencyKey. The database accepts the first INSERT and rejects the second duplicate key. The handler returns the original booking, preventing a duplicate booking or double charge. section 8.5

Inspect an idempotency design by asking:

  • Where is the duplicate-write guard: a key, a lock, or a constraint? section 8.5
  • Does the guard run inside the atomic database transaction with conflict checks and the core write? section 8.4
  • Which external calls need their own keys? A Stripe refund can be issued twice when a retry follows a network timeout. section 7.5
Figure 8.8 A double-clicked "Confirm" sends two requests with the same idempotencyKey. A UNIQUE constraint lets the first INSERT succeed but rejects the second, creating one booking instead of a double charge.

Follow the two-request sequence to see how one shared idempotencyKey and a UNIQUE constraint turn a double submission into one booking. section 8.5

How Crack Any Codebase with AI covers it

How deep it goes
Explains deterministic key derivation, UNIQUE enforcement, transaction placement, and external-call risks without showing implementation code.
Examples
Uses double-clicked bookings, stalled POST retries, and repeated Stripe refunds to expose duplicate effects.
What it assumes
Builds from database columns and UNIQUE constraints before connecting them to transactions, retries, and asynchronous side effects.
What you can do after
Diagnose/debug with it by locating duplicate-write guards and testing whether retries return prior results without repeating side effects.
How it connects
Connects idempotency keys to database transactions, UNIQUE constraints, retries, concurrency control, and the outbox pattern.

Also explained in

Compare how 4 books explain idempotency key →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Crack Any Codebase with AI. The section links point to the parts of the book it draws on.