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 real competitor is a shell script in a crontab, and it usually looks like this:

curl -s "https://api.example.com/v1/launches?limit=100" \
  | jq -r '.data[] | [.id, .name, .net] | @csv' \
  | sqlite3 -csv launches.db ".import /dev/stdin launches"

It works on the day you write it. Then the API answers 429 and curl pipes an error page into jq. Or the API has a second page, and the script never asks for it. When the job dies halfway, the rerun inserts the same rows again or trips over the primary key, depending on how the table was made. A field that starts arriving as a string goes unnoticed until a chart looks wrong. Retries, backoff, pagination, incremental state, idempotent writes and schema drift: that’s the list, and shell scripts get every item on it wrong in predictable ways. (To be fair, curl --retry covers the first two.)

An agent edits the wrong config file, then spends forty minutes trying to repair its own repair. The user files a bug with a screenshot of the last message. The maintainer asks for logs, and the logs live in four places: the provider’s usage page, the tool server’s stdout, the framework’s debug output, and a terminal scrollback that closed with the window. Nobody can say what the agent saw on turn six.

Point wrk at an MCP server and you get a clean report: every response a 200. Some of those 200s carry isError: true results, and nothing in the output says what the tool definitions cost the model on every turn. The tool is measuring requests per second. An agent runs a workflow, and what the server costs it is latency per call times calls per task, plus the tokens each response and each definition puts into its context.

“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.

A team wants to delete GET /v1/invoices/{id}/legacy-pdf. A search across the main repo finds no caller, and the gateway logs show zero hits in the last 30 days. The route goes out in a cleanup PR. On the first business day of the next quarter, a partner’s reconciliation job starts failing: it calls that endpoint four times a year, and nobody on the team knew the partner was still there.

You test an MCP server by chatting with it. Ask for the open bugs, get the open bugs, ship it. The model never sends limit: "ten", an empty path or a 200 KB query while you’re watching, so those paths stay dark until a real session hits one. Say it’s the limit. The handler throws, the framework wraps the exception in a 40 KB stack trace, and the model reads all of it, adjusts, and retries with the same bug in a new shape.

Ask a launch schedule API when a rocket flies and you get one date. Ask what the date was last Tuesday, or how many times it has moved, and there’s no endpoint for that. Most APIs describe the present. Prices, timetables, government datasets and status pages all change in place, and the old value is gone the moment the new one is written. That’s a pity, because launch dates slip so often that the list of changes in a launch schedule is more interesting than the current date.

Your OpenAPI file marks shipping_address as required on GET /orders/{id}. After Tuesday’s deploy, about one response in 300 leaves it out, because a new code path for orders created by the import job skips the field. The docs still say required. The tests still pass, since nobody wrote one for import-job orders. A client with a strict deserializer starts throwing on 0.3% of order pages, and the first report you get is “sometimes the order screen is blank”.