Pick any five public APIs and look at what comes back on a failed request. One returns {"error": "invalid_token"}. Another nests it: {"errors": [{"code": 1042, "msg": "..."}]}. A third sends {"success": false, "message": "Something went wrong"} with a 200 status, which is its own sin. Every client has to learn every shape, and every shared tool, from SDK generators to API gateways, has to guess.

The status code already says what class of failure happened. What it can’t say is which problem, in enough detail for a program to act on. That gap is what RFC 9457, Problem Details for HTTP APIs, fills. It was published in July 2023 on the IETF standards track, written by Mark Nottingham, Erik Wilde and Sanjay Dalal, and it obsoletes RFC 7807, the 2016 version most people still cite.

A client sends a POST to create a payment. The server charges the card, writes the record, and starts sending the response. Then the connection drops. The client sees a timeout and has no way to tell whether the charge happened. If it retries, the customer may pay twice. If it doesn’t, the order may never complete.

Every API that creates or changes something over a network has this problem. GET, PUT and DELETE are idempotent by definition in HTTP, so repeating them is safe. POST and PATCH aren’t. The fix most payment APIs settled on is a client-generated key sent with the request, which the server uses to recognize a retry and hand back the original answer instead of doing the work again.

“The API is slow” starts a hunt. Somebody opens the APM dashboard, somebody else greps the load balancer logs, a third person checks whether the database is on fire. An hour later the team has three theories and no measurement. One request, timed phase by phase, answers the first question in under a second: whether the time went to name lookup, the TCP connect, the TLS handshake, the server or the transfer of the body.

The HTTP status code specification is 30 years old, fully documented, and widely misimplemented. The misimplementation is not ignorance — most API developers know that 200 means success and 404 means not found. It is the edge cases where the correct status code requires a moment of thought that the wrong choice gets made, and the wrong choice gets propagated to every consumer who must now handle an error that does not mean what the specification says it means.