Error Handling and Problem Details
A developer's integration fails at 2 a.m. with {"error": "Something went wrong"}. They cannot tell if their input was wrong, their token expired, or BookNook is down. Good error responses are the part of an API people remember most, because they arrive at the worst moment.
The rule
Right status for machines, clear detail for humans, one shape for all.
Every error answers three questions:
- What kind of failure? The HTTP status code, so clients and tools can react without parsing text.
- What exactly went wrong, and how do I fix it? A human-readable message, specific enough to act on.
- Where do I look it up? A stable error type and, ideally, a request id for support and logs.
Instead of inventing a format, use the standard Problem Details format, first defined in RFC 7807 and updated by RFC 9457. It has its own media type, application/problem+json, and a few standard fields:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://api.booknook.example/problems/book-unavailable",
"title": "Book is not available",
"status": 409,
"detail": "Book 42 is on loan until 2026-10-09.",
"instance": "/v1/loans",
"available_from": "2026-10-09"
}type: a URI naming the kind of problem; the same for every occurrence, and it can point to documentation.title: a short, fixed summary of that type.status: the HTTP status, repeated for convenience.detail: what went wrong this time.instance: which request or resource it concerns.
You may add extension fields, like available_from above, or an errors list for validation failures that names each bad field.
What errors must not contain: stack traces, SQL, internal hostnames or secrets. Log those on the server under a request id, and give the caller only the id.
The shortcut
Write every error by filling three blanks: status → type → detail. If you cannot fill detail with something the caller can act on, the error is not finished.
Status
The JSON is valid, but the values break rules:
422.
Drills
Answer fast — trust the rule.
What media type does a Problem Details response use?
In Problem Details, which field changes from one occurrence of the same problem to the next?
A database query crashes. What should BookNook return to the caller?
Which error message is most useful to a developer?
Remember
- Right status for machines, clear detail for humans, one shape for all.
- Shortcut: status → type → detail, and detail must be actionable.
- Trap: 200 with an error body, vague messages, and leaking stack traces.