Glossary
Problem Details
Problem Details is a standard format for the body of an HTTP error response: a small document with a fixed set of fields — a type identifier, a short title, the status, a human-readable detail and the instance it applies to. Its value is not that errors become readable but that they become machine-readable in the same way across every API that adopts it, so a client can branch on a stable identifier instead of matching on a sentence.
The fields it standardises
A type: a URI identifying the kind of problem. It is the field clients branch on, and it is stable even when the wording changes.
A title: a short human-readable summary of that type, which should not change from one occurrence to the next.
The status code, repeated in the body so that a stored or forwarded response is still interpretable.
A detail: an explanation specific to this occurrence, which is the field that may vary.
An instance: a URI identifying the specific occurrence, which is where a correlation identifier naturally goes.
Extension members are allowed, so an API can add its own fields without leaving the format.
Why a stable identifier matters more than a good message
A client that matches on the message text breaks the day someone improves the wording, and the break is silent because the response is still a valid error.
A client that branches on a type URI keeps working through any number of message revisions and translations.
It also makes error handling reviewable: the set of types an API can return is enumerable, and a client's coverage of them is checkable.
None of that requires the format — a bespoke error shape with a stable code field achieves the same thing. The format is one fewer decision and one fewer thing to document.
What belongs in the detail, and what does not
What the caller can act on: which field failed validation, which limit was exceeded, what to change.
A correlation identifier, so a support conversation can be tied to a log entry without the caller quoting a timestamp.
Not a stack trace, not a database error, not a filesystem path. Those describe your stack to whoever asked, and they belong in your log keyed by that same identifier.
Not a message that differs depending on whether a record exists, which lets a caller confirm identifiers one request at a time without ever seeing data.
How it relates to what an audit observes
An error-disclosure check reads the responses an API really returned and looks for traces, database errors, debug output and server paths.
A Problem Details body containing only the standard fields passes that trivially, because there is nowhere in it for those to go.
The format is not required for a clean result, and adopting it does not by itself remove anything an error was already disclosing.
What is observed is what the response contains, not which format it claims to follow.
Frequently asked questions
- Do I have to use this format?
- No. A bespoke error shape with a stable machine-readable code achieves the same thing. The format saves you designing one and documenting it.
- Why put the status code in the body when it is already in the header?
- So a response that has been stored, logged or forwarded is still interpretable on its own. The two must agree — a mismatch is worse than either.
- Can I add my own fields?
- Yes, extension members are explicitly allowed. The standard fields are a floor, not a ceiling.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website