Idempotency

In 1 minute

A request is idempotent when doing it twice has the same effect as doing it once. A booking can succeed on the server while its answer is lost on the way back; the browser then retries. To make that safe, the browser sends one random idempotency key per booking intent, and Postgres stores it, unique per user. A repeat with the same key gets the first booking back, and no seats are taken twice.

Picture it

sequenceDiagram
  participant B as Browser
  participant A as API + Postgres
  B->>A: book 2 seats, key K
  A->>A: booked #b1, seats -2, COMMIT
  A--xB: 200 #b1 (answer lost)
  B->>A: retry: book 2 seats, key K
  A->>A: key K already has #b1, write nothing
  A-->>B: 200 #b1 (same answer)

How it works

1. One key per intent. The booking form makes a UUID when the user decides to book. Every retry of that booking sends the same key; a changed quantity gets a new key.
2. Look it up under the lock. Inside the transaction, right after locking the event row, the query looks for a booking with this user and key. Found: return it, write nothing.
3. Same or different? The service compares event and quantity. Same: a replay, answer 200 with the first booking. Different: 409 “This idempotency key was already used for a different booking”.
4. The constraint decides races. A UNIQUE constraint on (user, key) stops two copies that arrive at the same moment. The loser’s whole transaction, seats included, rolls back.

In MiniTickets

The key lives in the booking row itself, so it commits or rolls back together with the booking and the seats; it can never disagree with them (apps/api/src/queries/bookings.ts → createBookingTx).

The browser retries a booking at most twice (3 tries, after 1 s and 2 s), only on network errors and 5xx, never on a 4xx (apps/web/src/features/bookings/lib/booking-retry.ts → shouldRetryBooking). It is the only mutation that retries, and only because of the key.

Measured locally (pnpm demo:idempotency): 10 copies of one request gave 10 answers of 200, one booking id, one row, and only 2 seats taken.

Play the booking flow on the map →

See it in AWS

Console

Nothing to see in the console: the key is a column in Postgres. The API log has a debug line “replayed for a repeated idempotency key”.

CLI

aws logs tail /minitickets/dev/api --since 10m --filter-pattern replayed

Code

apps/api/src/services/bookings.ts → bookTicket

Break it

Symptom	Cause	Where to look
A user is charged twice for one click	The client made a new key per retry	The form’s key handling
A retry of the last seats says “Not enough seats left”	The key lookup ran after the seat check	The order inside the transaction
409 “key was already used”	The client reused a key for a different booking	Make a new key per intent

Say it in an interview

Say it like this (20-30 seconds)

The browser generates a UUID per booking intent and sends it with every retry. The bookings table has a unique constraint on user and key. Inside the transaction, after locking the event row, we look up the key first: if a booking exists we return it unchanged, and a different payload with the same key gets 409. Two simultaneous copies are settled by the constraint. Because the key lives in the row, it can never disagree with the booking.

Follow-ups

Why check the key before the seat check?

If the first copy took the last seats, the seat check would now say “not enough seats” for a booking the user already has. A repeat must get the first answer, whatever changed since.

Why not keep the keys in Redis with a TTL?

Redis and Postgres share no transaction. A crash between the two writes leaves them disagreeing, and an evicted key silently drops the protection. Keeping the key in the booking row avoids both.

Is the key scoped per user? Why?

Yes. Two users could, by chance, send the same key. Scoping by user means they never share a booking.

What is the trade-off of never expiring keys?

They cost about 16 bytes plus an index entry per booking, forever. Fine at our size. A payment API would store full responses for about 24 hours instead.

Advanced: Where the logic lives

The query only reports “created” or “existing”. Whether an existing booking is the same request is a business decision, so the service compares the event and the quantity. A failed booking stores nothing, so retrying it with the same key simply tries again: “not enough seats” may be wrong a second later.

Checkpoint

Answer these without scrolling up. If one feels hard, reread that section.

1. What does idempotent mean, in one sentence?
2. When does the browser make a new key, and when does it reuse one?
3. What does the API answer to the same key with a different quantity?
4. What settles two copies that arrive at the very same moment?
5. Why does only the booking mutation retry automatically?

Redraw it from memory: the sequence: book with key K, answer lost, retry with K, the same booking returned

Try this: run pnpm demo:idempotency on the local stack and check how many booking rows it made

Mark this page as read