API error triage should preserve status code, response body, and caller expectation separately

API error triage works better when the status code, response body, and caller expectation are recorded as separate facts.

A common debugging mistake is to collapse the whole failure into one sentence: “the API returned an error.” That hides the contract mismatch. A 401 with a structured JSON body, a 404 from the router, a 429 from a rate limit, a 500 HTML error page, and a network-level CORS failure all require different next steps. The caller may also expect a shape the server never promised.

A useful triage note has six fields. Request: method, URL, query, body shape, headers that matter, and caller identity if relevant. Response: status, content type, body shape, cache headers, and trace or request ID if available. Caller expectation: what the frontend, job, or integration expected to happen. Contract source: OpenAPI file, typed client, docs, tests, or a known route handler. Reproduction: exact input that failed. Classification: auth, validation, missing resource, rate limit, server bug, parse error, CORS, or timeout.

Separating those fields prevents premature fixes. If the status code is right but the frontend expected the wrong body, the fix may be in the client. If the body is right but content type is wrong, the parser may fail. If a proxy changes a 500 into an HTML page, the API route may not be the first layer to inspect.

The goal is to make the next person able to reproduce the same failure without guessing which layer produced it.

API error triage should preserve status code, response body, and caller expectation separately

// COMMENTS

ON THIS PAGE