Read the naive version as an ordering problem rather than a caching problem. Check the store for the key, and if it is empty run the controller, save the response under the key, then return it [5]. Two gaps sit in that order. The first is between the read and the controller call, which is the case the article demonstrates with two workers that both read no record and both execute [9]. The second is between the controller returning and the save landing, and a lock does nothing for that one [3].
The second gap is a transaction-boundary question. Shared idempotency state plus Symfony Lock closes the race [10], but the record saying "we already did this" is a different write to a different system than the order row. If business data commits to a database and the idempotency record goes to a cache, no single commit covers both. Die in between and you have order #742 with nothing to replay [3], which is the exact state the key was bought to prevent. For the guarantee to hold end to end, the record has to be written inside the same transaction as the business effect, or reserved before execution and reconciled afterwards. Neither is free, and which of the two a bundle assumes is the first thing I would go looking for in its docs.
Now the fingerprint. Six fields go in: HTTP method, logical operation, path, normalized query parameters, normalized Content-Type and the raw request body, hashed to SHA-256 [6][1]. Query parameters and Content-Type get normalized, but the body stays raw [6], which means byte equality, not semantic equality. A retry that re-serialises the same object with map keys in a different order, or a client that stamps a fresh trace id into the payload, produces a different digest and collects a 422 [7]. The real question to answer before adopting this isn't about the hash function at all: it's whether your HTTP client buffers the exact bytes it sent the first time and replays those, or rebuilds the body from an object on each attempt.
The 422 is the part of the design I would defend. The author's stated line is that idempotency should protect against duplicate execution, not hide application bugs [8], and returning the first response to a second, different payload under the same key would be worse than plainly failing [14]. Handing a client a 422 at 3am is unpleasant, but it beats handing it someone else's order id.
What a server-side store cannot cover is anything the server already said to a third party. The article's own list of work that may already have completed before the response was lost includes a call to a payment provider [2]. That call needs its own key at the provider, and a replayed local response says nothing about whether the provider deduplicated. The same holds for a message already handed to a broker.
The writeup promises to name what cannot be guaranteed [12]. The text supplied to me breaks off mid-sentence while making the point that local state stops working once you run multiple PHP workers, containers or application nodes [11], so that list is not in front of me and I am not going to guess at it. Everything above the break is sound: the fingerprint decision is the right one, and the choice to fail loudly on key collision is better engineering than a silent replay.
