An Error Response That Does Not Say What to Do Is Not an Error Response
Key takeaway: Error responses are part of the API’s interface, and a good one tells the client not just that something failed but what failed, why, and what to do about it — an error that leaves the client guessing is a failure of the API design, not of the client.
What a Useful Error Response Contains
A useful error response tells the client three things: what went wrong, why it went wrong, and what to do about it. The status code communicates the broad category of failure, a machine-readable error code identifies the specific problem so the client can handle it programmatically, and a human-readable message explains the situation in a way a developer can act on.
| Element | Purpose |
|---|---|
| HTTP status code | Broad category of failure |
| Machine-readable error code | Specific problem, handleable in code |
| Human-readable message | Explanation a developer can act on |
| Relevant details | Field names, identifiers, validation specifics |
The machine-readable error code is what lets a client branch its behaviour — retry on a transient failure, prompt the user on a validation failure, redirect to login on an authentication failure — and without it, the client is forced to parse the human message or guess from the status code, which is fragile and breaks when messages change.
The Common Failure Modes
The most common failure is an error response that is too vague to act on — a generic message like “an error occurred” with no code and no detail, which tells the client nothing about what failed or what to do, and is essentially useless for debugging or for programmatic handling.
Another common failure is leaking too much internal detail — stack traces, internal identifiers, or database error messages exposed to clients — which is a security and operational concern, since it reveals internal implementation details to anyone who can call the API, and it is not actually useful to a well-designed client that should be handling errors by code rather than by reading internal messages.
The Balance Between Useful and Safe
The right balance is to give clients enough structured information to handle the error programmatically and to understand what to do — a specific error code, a clear message about the problem, and the specific fields or identifiers involved — while keeping internal implementation details out of the response, since those belong in server-side logs where the operators who need them can see them, not in responses sent to clients.
Consistency Across the API
Error responses should be consistent in structure across the entire API — the same fields, the same format, the same conventions — so that a client that has learned to handle errors for one endpoint can apply the same logic everywhere, rather than having to handle a different error shape for each endpoint, which multiplies the client’s integration effort and is a common source of client-side bugs.
The Bottom Line
Design error responses as a deliberate part of the API interface, including a status code, a machine-readable error code, a clear human-readable message, and the specific details needed to act on the error, while keeping internal implementation details out of responses and in server-side logs. Keep the error structure consistent across the entire API so clients can handle errors uniformly.
