Oh man, the classic "200 OK with error: true buried in the JSON body" trap. That is the absolute bane of distributed systems engineering, Mihai.
What makes this failure mode so terrifying in AI-generated code is that it causes silent operational death:
- The monitoring dashboards stay completely green (HTTP 200).
- The retry logic looks textbook-perfect during PR review.
- The unit tests pass with flying colors.
- Yet zero business transactions actually succeed, and user data quietly evaporates.
A loud 500 Internal Server Error is a blessing compared to a polite 200 OK that swallows failure.
And this is the purest expression of the Context Ceiling: LLMs are trained on millions of textbook REST tutorials, but enterprise production is littered with legacy endpoints, GraphQL wrappers, and third-party APIs that shamelessly violate HTTP semantic standards.
Your practical check is pure gold: "Verify against a real captured payload from production, not the API docs." Because API documentation reflects the original author's optimistic intentions; real payloads reflect what the legacy server actually does in the wild.
Definitely incorporating that rule into our client review checklists. Brilliant contribution as always!
The timeout mismatch example is a good one because it's not even a case of the AI being wrong about syntax, it's wrong about a fact it never had access to. The one I keep running into in agent-generated integration code is subtler: retry logic that assumes an HTTP-level failure contract when the actual downstream API returns 200 with the real error buried in the response body. Nothing in review catches it because the retry policy looks completely sane in isolation, and it only shows up once you're staring at logs full of successful-looking calls that quietly did nothing. Writing down the tribal facts before merging is a good habit, but I'd add a cheap mechanical check on top: grep the generated code for every place it treats HTTP status as ground truth and cross-check that assumption against a real captured response from that specific downstream, not the API docs.