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.

API documentation is where most APIs fail their consumers silently. The API itself may be well-designed, reliable, and feature-complete. If the documentation is incomplete, inaccurate, or organized without regard for how developers approach integration tasks, the API will generate support tickets, incorrect integrations, and the quiet abandonment of developers who find a better-documented competitor.

The documentation failures that cause the most damage are predictable: reference documentation without examples, error responses that are documented without the conditions that produce them, authentication sections that explain the mechanism but not the specific steps to obtain credentials, and code examples that work when first published and become outdated as the API evolves.