production
Error Response Envelopes
Return errors in a single consistent shape so clients can handle them generically — instead of guessing what each endpoint returns.
When every endpoint reports failures differently — one returns a bare string, another a nested object, a third just a status code — clients must write bespoke error handling for each, and they inevitably get it wrong. A consistent error envelope is a single, predictable JSON shape that every error response in the API uses, so a client can parse and handle failures generically no matter which endpoint produced them.
Standardized parking tickets — same fields in the same boxes, regardless of which officer wrote it.
Key Concepts
1
A good envelope carries the information a client actually needs to react and a human needs to debug. At minimum that is a machine-readable error code (a stable string like INSUFFICIENT_FUNDS that clients can branch on, distinct from the HTTP status), a human-readable message, and usually a correlation or request id that ties the response to a server-side log entry for support. For validation failures it includes a structured list of field-level errors so a form can highlight exactly which inputs were wrong and why. The industry is converging on RFC 9457 / 7807 "Problem Details for HTTP APIs," which standardises fields like type, title, status, detail, and instance — adopting it gives you a well-understood shape for free. The envelope pairs with correct HTTP status codes: the status conveys the category, the body conveys the specifics.
INSUFFICIENT_FUNDStypetitlestatusdetail
2
The pitfalls interviewers want you to name are leaking internal details — stack traces, SQL, framework exceptions — into the error body, which is both a security risk and useless to clients, and using the message string as the thing clients branch on, which breaks the moment you reword it (that is what the stable code is for). The clean approach is to centralise error formatting in one place (a global exception handler) so the consistent envelope is produced uniformly, internal detail stays in the logs keyed by the correlation id, and clients get a stable, parseable contract for every failure.