Errors That Help Instead of Hurt
You'll learn to
- -Design a consistent, machine-parseable error response shape using RFC 7807 Problem Details
- -Distinguish a good validation error response (field-level, actionable) from a vague, unhelpful one
A status code alone tells a client what category of failure happened; the response body is where an API explains what specifically went wrong and, ideally, how to fix it. Every API that grows past a handful of endpoints eventually needs a consistent error shape - the question is whether that consistency is designed deliberately or accumulated ad hoc, one inconsistent error format per endpoint.
RFC 7807: Problem Details for HTTP APIs
{
"type": "https://api.example.com/errors/insufficient-funds",
"title": "Insufficient Funds",
"status": 402,
"detail": "Account balance ($42.00) is less than the requested withdrawal ($100.00).",
"instance": "/accounts/42/withdrawals/883"
}- -`type`: a URI identifying the specific error category - clients can match on this programmatically without parsing human-readable text.
- -`title`: a short, human-readable summary of the error category (stable across occurrences of the same error type).
- -`status`: the HTTP status code, duplicated in the body for convenience when the body is logged or inspected separately from headers.
- -`detail`: a human-readable explanation specific to this occurrence.
- -`instance`: a URI identifying this specific occurrence, useful for support/debugging correlation.
The value of standardizing on a shape like this is that client error-handling code can be written once, generically, against `type` and `status`, instead of every endpoint requiring its own bespoke error-parsing logic - exactly the same "consistency reduces integration friction" principle from the resource-naming chapter, applied to failure responses instead of success ones.
Field-Level Validation Errors
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"errors": [
{"field": "email", "message": "must be a valid email address"},
{"field": "age", "message": "must be at least 18"}
]
}A validation error that just says "invalid input" forces the client (and the human debugging it) to guess which field and which rule failed. Returning every failing field at once, with a specific message per field, means a client can surface all the problems in one round trip instead of fixing one field, resubmitting, discovering the next error, and repeating.
Never leak internal implementation detail into an error message a client can see - a stack trace, a raw database constraint name, or an internal file path in a `detail` field is both a security exposure and useless to the caller, who cannot act on it.
A validation error currently returns `{"error": "invalid request"}` with no further detail. The interviewer asks how you'd improve it.
"I'd just make the message more descriptive, like 'invalid request - please check your input.'"
"I'd restructure it to return field-level detail - which specific fields failed and why, ideally as an array so multiple problems surface in one response instead of one at a time. I'd also standardize the overall shape using something like RFC 7807 Problem Details, so every error across the API - not just this one endpoint - has a consistent, machine-parseable structure clients can build generic error-handling logic against."
What is the benefit of standardizing error responses on a shape like RFC 7807 Problem Details?
Design The Error Whisperer in the API Design Lab's REST Foundations act.