Keep Replay Outcomes Out of the Generated Page
A checkout service documented Idempotency-Key on POST /payments . Overnight, a generator rewrote the page from the OpenAPI description fields. The new paragraph said a repeat call "always returns the original response body." A merchant retried a timeout. The API answered 409 with code: replay_conflict and a short error body, not the first 201 . Support quoted the page. Engineering quoted the…
The API page outlines the caller's expectations and makes guarantees. Orientation includes the header name, sample key, and link for further reading. A promise details the replay outcome, such as status code, body identity, key scope, retention, and whether a second call can generate a new charge. Models can draft orientation well, but they do not own promises.
Guide sentences may change with each release, while contract sentences remain until a human edits them. The composite regeneration process affected 11 sentences, with five asserting replay behavior being the defect. Orientation should be placed in guide.md, while promise details should reside in freeze.md.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.