Loading today’s stories
Build1 distinct publisher2 min readUpdated
A dev.to teardown of payment idempotency argues the header is a token and the guarantee is a document. The parts nobody writes down fail during outages, when nobody is looking.
The Engineer · Build desk
Compiled by The EngineerSomething wrong?How this is made
Each of the four questions the piece names has an answer that costs money when it is wrong, and the table it prints tells you which of them a database can even hold [1][13]. The state column takes exactly three values, in_flight, succeeded and failed, sitting next to response_status, response_body, resource_id and locked_until [13]. That is storage for the answers. It is not the answers.
Take failures. The stated promise is that every retry gets the original response back, same status and same body, byte for byte [6]. A row written in state failed is therefore a commitment: whatever you put there, you have agreed to serve it again to the next caller who presents that key [15]. Deciding which failures are worth remembering is deciding which of your errors become permanent for a given key, which is not a caching preference.
Retention is the question the schema quietly declines. The columns as printed carry created_at and locked_until and nothing that expires a row [13][14]. Absent a sweeper and a documented window, the answer is forever, and forever is a stronger guarantee than anyone means to offer.
The in-flight case is where the supplied text stops, mid-insert [18]. It is also the one with no defensible default, because the fix that removes the race puts the row in before the work happens [12]: you have claimed the key, you have no response to replay, and you cannot run the charge twice [6]. Insert-first is what forces you to name that state at all, and naming it in a CHECK constraint is not the same as telling callers what they receive.
There is a reason this stays unmonitored. RFC 9110's version of idempotency constrains server state and says nothing about what the caller sees [4]. That maps neatly onto the two halves of the promise: the at-most-once half is checkable against your own tables, and the byte-for-byte replay half is only observable from the client that never got the first response [19]. One half you can assert in an integration test. The other half you learn about from a support ticket. The piece calls the result the worst outcome available, double charges made rarer without being made impossible, with nobody watching [2].
The deliverable, then, is prose: four sentences about equivalence, expiry, concurrency and error caching, written where callers can read them. The header is what you ship after that.
Follow any of these and your For You feed starts watching them — no settings page required.
Ranked by verification strength, evidence, and original report placement.
RFC 9110 defines PUT and DELETE as idempotent, meaning sending the request twice leaves the server in the same state as sending it once; POST is deliberately excluded, which is why the Idempotency-Key header exists as a way to bolt the property onto POST.
A dev.to article argues that a key is a token while idempotency is a contract, defined by four answers: what counts as the same request, how long the answer stays valid, what a caller gets when a retry lands while the first attempt is still running, and which failures are worth remembering.
Skipping those answers makes double charges rarer without making them impossible, which the author calls the worst outcome available, because now nobody is watching for them.
The RFC definition constrains server state and says nothing about what the caller sees, even though the caller is the entire reason for doing it.
The handler people write first returns {"status":"ok"} when it finds the key already seen; the client retried because it never saw the first response, and what it needs back is the charge id from attempt one, so it is told a charge exists with an id it will never learn.
The promise has two halves: the work happens at most once, and every retry gets back the original response with the same status and the same body, byte for byte.
Evidence-backed comparisons of source perspectives and observed adoption signals. Read the methodology
Which Builder, Operator, and Investor concerns the observed source mix emphasized—not a truth score.
Evidence, demonstrated adoption, hype gap, incentives, and confidence are assessed independently, each on its own current evidence. How these are measured.
Self-contained mechanism, single uncorroborated source
The core reasoning is verifiable inside the text: the TOCTOU race, the fingerprint-mismatch dilemma, and the re-serialisation failure modes are demonstrated with concrete code, a SQL schema, and a claiming INSERT, and the standards framing is a faithful restatement of PUT/DELETE versus POST semantics. Evidence is capped, however, because the cluster contains exactly one source item, no primary standard or vendor documentation, and no measurement of how often the described failures occur.
No adoption signal in cluster
The supplied material contains no releases, deployments, benchmarks, usage disclosures, pricing or licence changes, or incident reports. The only external reference is a descriptive remark about Stripe's error response, which is not evidence of anyone adopting the pattern the article prescribes, so no adoption value is inferred.
Mildly overstated prescriptions, restrained framing
The framing is unusually disciplined for the genre — it defines a contract, shows the failing code, and explains the mechanism rather than promising a silver bullet. The small positive gap reflects that its strongest normative claims are asserted rather than demonstrated: rejection as the 'only correct answer', 409 over blocking, and the 'worst outcome available' characterisation carry more certainty than a single-source explainer with no incidence data can settle, and the prescribed schema itself omits the retention answer the article demands.
Practitioner authority, no product being sold
The observable incentive is reputational: an individual author publishing a technical teardown on dev.to, a developer platform where engagement accrues to strong, quotable framings such as 'idempotency is not a key, it's a contract'. There is no product, sponsor, or vendor promotion in the text, and the one commercial mention (Stripe) is used descriptively as a reference behaviour, so distortion pressure is low but non-zero.
Confident on argument, thin on corroboration
Confidence is moderate: the internal claims are directly quotable from the source and the derived readings follow from the article's own definitions, so what the piece says and why it holds together is clear. Confidence is held down by the single-publisher cluster, the absence of any primary standard or vendor documentation, the lack of adoption or incidence data, and a truncated body that omits part of the argued contract.
build
The NestJS default path puts the query inside the business rule, and nothing fails when it moves1 distinct publisher
build
Disabling Submit Fixes the Click, Not the Lost Response1 distinct publisher
build
One incident instead of two: what SKIP LOCKED actually buys you1 distinct publisher
build
Checkpoint the step, not the pipeline: four agents and one unguarded embed1 distinct publisher
Distinct publishers with included, body-backed reporting in this cluster.
dev.to
1 article · August 22, 2026