Should the app resend Request ride?
In a ride-hailing app, the request behind the Request ride button is POST /rides. It creates a ride, places a hold for the estimated fare, €18 say, on the rider's card, and starts looking for a driver. Riders send it from stadium exits and train platforms, where a request often reaches the server and its 201 Created answer dies on the way back. After 15 seconds the app has heard nothing, and it cannot tell that from a request that never left.
Resend, and the server does everything again: two rides, two drivers heading for the same gate, two holds on the card. Do not resend, and the rider taps again and books the second ride by hand. Why a network loses answers, and why delivery alone cannot be exactly once, is explained in Idempotency & exactly-once illusions; this article is about the tool that makes resending safe.
A name for the intent, not for the attempt
When the rider taps, the app generates a random, unguessable value, a version 4 UUID such as 7c1e9a40-…, and keeps it with the pending request. Every attempt to send that request, the first and each retry, carries it in a header: Idempotency-Key: 7c1e9a40-…. That value is the request's Idempotency Key. It names the rider's intent to get one ride, so the server can tell a repeat of that intent from a new one.
Generated in the HTTP layer, in the code that sends each attempt, the key would come out fresh on every retry, and the server would book each retry as a new ride. The key belongs to the rider's intent, not to each tap: stored with the pending request, it survives the app being killed and reopened, a tap while that request is still pending reuses it, and a new one is made only for another ride. When to send each retry, and how long to wait, is covered in Retry.
What the server writes down
The rides service keeps a key table, in the same database as the rides, with one row per key:
- the rider's account and the endpoint, which together with the key make up the row's unique identity, so the same UUID from another account, or on another endpoint, is a different row;
- a fingerprint of the request, a hash of its method, path and body;
- a status,
in_progressordone; - the response the first attempt produced, status code and body, once there is one.
Scoping the key to the authenticated rider matters for more than tidiness: another account that sends the same UUID, by chance or on purpose, cannot be handed the first rider's stored response.
When an attempt arrives with a key whose row is done and whose fingerprint matches, the service creates nothing. It returns the stored response, the same 201 with the ride the first attempt created, r-5512, and the app looks that ride up and shows the driver who is already on the way.
Every attempt carries the same key. The rides service claims the key before acting and turns it to done in the same transaction that creates the ride; the hold at the provider carries a key derived from the rider's.
Two attempts at the same moment
Looking up the key and then acting is not enough. The retry can reach a second server while the first attempt is still running there: the first attempt looks up 7c1e… and finds nothing, the retry looks it up a moment later and finds nothing either, and both go on to create a ride and place a hold.
So the service claims the key before doing any work, with an operation only one attempt can win: an insert under a unique constraint on account, endpoint and key, or an insert-if-absent in a key-value store. The winner's row says in_progress. The loser finds that row and, if its fingerprint matches (a mismatch is rejected, as the next section shows), has two acceptable answers: reply at once with 409 Conflict, saying the request is still being processed, so the app tries again a little later; or hold the connection, poll the row until it turns done, and return the stored response. Either way, one ride exists.
Same key, different ride
The fingerprint answers a question the key cannot. Suppose a bug in the app keeps the old key after the rider changes the destination from the north gate to the train station and taps again. The key matches a done row. A service that looked only at the key would return ride r-5512, to the old destination, with a 201 that says all is well. Comparing fingerprints catches it: the payload differs, so the service rejects the request with an error (the IETF draft that defines the Idempotency-Key header suggests 422) instead of replaying a response that belongs to a different request.
A crash between the claim and the answer
Claiming first opens a gap of its own: the service can die after the claim and before the response is stored, so the work is arranged for a retry to recover from any point.
The ride row and the stored response are written in one database transaction, the same one that turns the key's row from in_progress to done. A crash before that commit leaves no ride and no response, and a crash after it leaves both. There is no ride without a recorded answer for a retry to miss.
The fare hold cannot join that transaction, because it happens at the payment provider (why no ordering around a commit makes such a call safe on its own is shown in Idempotency & exactly-once illusions). So the service passes the key on: it sends the provider an idempotency key of its own, derived from the row's whole identity, account, endpoint and key (hold- plus a hash of the three), and a provider that supports such keys answers a repeat with the same parameters, inside the provider's idempotency window, with the hold it already placed. If the service dies after the hold and before the commit, the row stays in_progress. Once the claim is older than any attempt is allowed to run, say 60 seconds against a 10-second limit, the next retry takes the claim over with a conditional update that writes a new owner token on the row, so only one of two racing retries wins, and runs the steps again: inside the provider's idempotency window, the provider returns the existing hold and the transaction creates the ride. Past that window the key protects nothing at the provider, and finding out whether a hold exists becomes the reconciliation that Payments & billing integration describes. That transaction also checks that this attempt's token is still on the row, so a first attempt that was slow rather than dead cannot write a second ride when it wakes up. How holds and charges work at a provider is in Payments & billing integration.
How long a key lives
Keeping every key forever would grow the table without end, and a retry that arrives after its row is gone is a new request that books a new ride, so retention follows the client's retry window. If the app stops retrying a pending request after 10 minutes, and from then on asks the server for the rider's current ride instead of resending, keeping keys for 24 hours leaves a wide margin. Expiring them after 5 minutes lets a retry at minute 7 book a second ride.
A message handler that a broker redelivers to has no client key to rely on; it records the message it applied, as Idempotent Consumer describes.
Drawing it in Idempotent Processing
The Idempotent Processing Challenge opens with this request side: a client attaching an Idempotency Key to each mutating request, and a service storing processed keys and replaying the stored answer. Put a Retry node between the Client and the Service, and the Idempotency Key node beside the Service as the key table. Before you submit, ask your design two questions: what does a retry get while the first attempt still holds the claim, and what does it get after the server died holding it? The palette has no payment provider, so the second answer leans on the derived key you cannot draw. The queue half of the brief is Idempotent Consumer's.