On this page

Record the Response Before You Interpret It
A structured error document is a JSON object delivered under the media type application/problem+json. The body is only one of the three things worth capturing. The status line and the Content-Type header complete the picture, and each answers a question the other two cannot.
The HTTP status records what the server actually returned. The Content-Type records how the server announced the body. The body itself carries the problem information you will inspect field by field. A screenshot of a JSON object, pasted into a ticket on its own, establishes none of the first two facts.
| Evidence to capture | What it lets you verify |
|---|---|
| Actual HTTP status | Whether the body reports the same status |
| Content-Type header | Whether the body was announced as application/problem+json |
| Unmodified body | Which members and values actually arrived |
| Request context | Which call produced this response |
Keep the unmodified body next to any formatted copy you make. Reports have a way of shedding fields, and a formatted pretty-print is only trustworthy while the original remains reachable.
One more habit prevents a whole class of wasted debugging: label responses when more than one attempt is involved. A body captured from attempt one combined with a status read off attempt three produces a comparison that looks authoritative and describes a response that never existed. If the metadata was never recorded, say so plainly rather than reconstructing a status from the body’s own status member.
curl -is https://api.example.test/registrations \
-H 'Content-Type: application/json' \
-d '{"age": "twelve"}'
The -i flag is the cheapest insurance in this whole workflow: it keeps status and headers attached to the body they belong with.
A Worked Example, Invented End to End
Everything from here on walks a response invented for this guide. Its addresses and identifiers describe no real service.
Metadata: status 422, Content-Type application/problem+json.
{
"type": "https://example.test/problems/validation",
"title": "Invalid input",
"status": 422,
"detail": "age must be an integer.",
"instance": "/problems/demo-1",
"errors": [
{"field": "age", "rule": "integer", "received": "twelve"}
]
}
Five standard members and one extension. Each contributes something the others do not, and walking them in order is the fastest route from “the request failed” to “here is the correction and here is the proof.”
Format the Body Only After Capturing It
Formatting and interpretation are separate steps, and doing them in the wrong order is how evidence gets quietly replaced. Format a copy, yes — indentation exposes nesting mistakes that a one-line payload hides. But format into a new artifact and leave the original untouched, the way you would keep the original HTTP trace next to a debugger’s re-rendering of it.
const original = '{"type":"https://example.test/problems/validation","title":"Invalid input","status":422}';
const pretty = JSON.stringify(JSON.parse(original), null, 2);
// two artifacts now exist; the report quotes the original and displays the pretty one
The inspector on this site keeps the distinction built in: the source pane never changes, and the formatted tree is a view over it rather than a replacement for it. That separation, carried into your own notes, is what makes the eventual report verifiable instead of merely plausible.
One formatting rule deserves emphasis because it interacts with data: whitespace changes are safe, string content is not. A formatter that “normalizes” quotes or unicode inside strings is editing the payload, and a diff against the original will then show changes that the network never sent.
What the Media Type Does and Does Not Promise
The application/problem+json media type promises a specific shape: a JSON object with the five standard members available and extensions permitted. It does not promise which extensions exist, that detail is localized, or that type resolves. Promises about content live in the API’s documentation; promises about shape live in the media type registration.
That split explains a common review argument. A client team wants to hard-code problem.errors[0].field; a contract reviewer objects that errors is an extension. Both are right about their own layer. The resolution is a capability check in the client — read the type definition, branch on what the contract actually defines — rather than a negotiation over what the media type “should” include.
const isProblemDetails =
response.headers.get('content-type')?.includes('application/problem+json');
if (!isProblemDetails) {
// the body may still be JSON, but the problem-details reading does not apply
}
Type Names the Problem, Not the Outcome
The type member is a URI that identifies the class of problem. Two responses can share a type and still describe different failed requests, the way two invoices can share a billing category. The URI exists so that both humans and programs can resolve one definition and compare notes.
Resolving it, when the API documents it, answers questions the body does not: which fields this problem class covers, what retry behavior is expected, which extensions the API defines for it. A type you have never resolved is a guess about the contract, however familiar its title looks.
const problem = JSON.parse(body);
new URL(problem.type); // absolute? resolvable? documented?
// relative URIs resolve against the API base; opaqueness is allowed
If the URI is opaque — the API never serves a definition at that address — treat the member as a stable identifier and rely on the human-readable members for meaning. What you should not do is invent semantics from the slug. A type ending in validation tells you the category; it does not tell you which rules applied.
Title, Detail and Instance Answer Different Questions
The three human-readable members divide the labor cleanly, and most misreadings of structured errors come from merging them:
titlenames the class: Invalid input. It is allowed to be identical across thousands of responses. It is not the place to look for what was wrong this time.detailexplains this occurrence: age must be an integer. It is written for the developer reading it now, and it may reference the received value.instancepoints at the specific occurrence, often as a trace path. It is the member to quote when you escalate, because it is what the server side can look up.
"title": "Invalid input", // class, stable
"detail": "age must be an integer.", // occurrence, specific
"instance": "/problems/demo-1" // occurrence pointer
A practical consequence: automated alerting keyed on title lumps every validation failure into one bucket. Keying on type gives you the same grouping with a resolvable name, and including instance in the alert payload is what makes the ticket answerable on the server side.
When the Body Status and HTTP Status Disagree
The body’s status member repeats the intended HTTP status, and the two can diverge: proxies rewrite status lines, gateways turn timeouts into 502s, some frameworks wrap the original status inside the body while changing the transport one. The disagreement is information, not noise.
// transport status 502, body status 422
// the application-level failure was validation;
// the infrastructure failure came after it
Read the mismatch in this order. The body status describes what the application concluded. The transport status describes what arrived at your client. When the transport status is a gateway code, the application’s answer may still be recoverable — the request may have reached the service and failed validation there. When the transport status matches, the application answered directly and the body’s account is current.
What you should never do is repair the discrepancy by trusting the body and ignoring the wire, or the reverse. Record both, and let the report state the gap.
Extensions Belong to the API Contract
The errors array in the example is an extension member. Problem-details defines five standard members and explicitly invites APIs to add more, which is why no generic reader can know what errors, balance or traceId mean. The definition lives in the API’s documentation, ideally linked from the problem type.
| Member | Defined by | How to treat it |
|---|---|---|
type, title, status, detail, instance |
RFC 9457 | Standard semantics, safe to read generically |
errors |
This API’s contract | Read the docs; do not assume shape |
Verify the extension before automating against it. One API’s errors is an array of objects with field and rule; another’s is an array of strings; a third omits it for non-validation problems. A script written against one response class will throw on the second and silently pass over the third.
if (Array.isArray(problem.errors)) {
problem.errors.forEach(e => {
// shape verified against the contract, not assumed
console.log(e.field, e.rule, e.received);
});
}
Inspect the Payload and Write Down Observations
Paste the body into the inspector on this site and work through it with two questions per member: what does the format promise here, and what does this API’s contract add? The source pane keeps the token exactly as received, so a numeric status is visibly a number and an instance is visibly a string — distinctions that matter the moment someone writes an equality check.
Expected observations for the invented example, written out the way a report should state them:
- The document is a single JSON object; no array or scalar at the top level.
- All five standard members are present with their conventional types.
status(422) matches the captured transport status.errorsis an array of objects; its members are contract-defined, not standard.- Nothing in the body requires reading a second endpoint to interpret, assuming the
typedocumentation is available.
Stating observations in full sentences sounds ceremonial until the day a report is forwarded to a team that has never seen the payload. Then the difference between "errors": [...] and “errors is an array of {field, rule, received} objects per the contract” is the difference between a follow-up question and a fix.
A Second Walkthrough: The Same Method on a Gateway Error
One more invented response shows the method holding up when the layers disagree. Suppose the same request now returns transport status 502 with Content-Type text/html, and the body is an HTML error page rather than a problem document.
The disciplined reading takes three sentences. First: this response is not problem-details, so the five-member reading does not apply. Second: the gateway that emitted it has no view into the application’s validation outcome, so the earlier 422 answer is stale — the request may or may not have been processed. Third: the correct next action is a retry with the same idempotency key, not a re-submission of corrected data, because the failure reported is infrastructural.
curl -is -X POST https://api.example.test/registrations \
-H 'Idempotency-Key: 7f9c2e11-demo' \
-H 'Content-Type: application/json' \
-d '{"age": "twelve"}'
Notice what the method prevented. Without the media-type check, the HTML page might have been parsed as if it were a problem document, or the 502 might have been logged as a validation regression. The three-sentence reading costs less time than either mistaken path, and it produces exactly the sentence the on-call engineer needs: infrastructure answered, application outcome unknown, retry keyed.
Assemble a Report Someone Can Act On
The troubleshooting report that gets fast answers contains five items, none of them optional:
- The unmodified response body, in a code block.
- The transport status and Content-Type as received.
- The triggering request, with secrets redacted.
- The
typeURI and a note on whether its definition was resolvable. - The specific observation that looks wrong, quoted from the body rather than paraphrased.
Formatting the JSON before inclusion is worth doing for readability, and the workbench does it locally in the browser — no upload, no model call, no code execution. What formatting must never do is replace the original: attach both, mark which is which, and let the reader verify that the pretty version is a faithful copy.
Run the same capture discipline on the next structured error you meet, and the conversation shifts from “what does this mean” to “here is what it says; here is the part that contradicts the contract.” That is the shift that turns error reading from interpretation into verification.