Designing Error Responses People Can Actually Debug

{"error": "something went wrong"} is a genuinely common API error response, and it's almost useless. It tells the caller that a failure happened — information they already had, because the request failed — without telling them anything they didn't already know: what specifically went wrong, whether it's their fault or the server's, or what they could plausibly do differently.
A good error response answers three questions a developer debugging an integration actually has, every single time: what happened, why, and what (if anything) can I do about it.
What a genuinely useful error body includes
A few fields consistently show up in error response designs that people don't complain about:
- A machine-readable error code or type, distinct from the human-readable message — something a client can safely branch on (
"error": "insufficient_funds") without parsing a sentence that might get reworded later. Comparing a status message with.includes("insufficient")is the kind of code that quietly breaks the next time someone edits the wording for clarity. - A human-readable message, for logs, error pages, and developers reading a response during debugging — separate from the machine-readable code, so one can be improved without breaking the other.
- Which specific field or parameter was the problem, for validation errors — "the email field must be a valid email address" is debuggable in a way "validation failed" is not, especially on a request with a dozen fields.
- A request or trace id, so a support conversation or bug report can reference the exact failed request instead of a rough description of when it happened.
RFC 7807 ("Problem Details for HTTP APIs") standardizes a shape for a lot of this — type, title, status, detail, instance — specifically so that error responses across different APIs and services can share a predictable structure instead of every team inventing its own. You don't have to adopt it wholesale to benefit from the underlying idea: pick a consistent shape, document it once, and use it everywhere in your API rather than letting each endpoint's error format be an accident of whoever wrote it.
The mistake that's easy to make in the other direction
There's a real security tradeoff here too, and it cuts the other way from "always include more detail." An error message that echoes back exactly why authentication failed ("no account exists with that email" vs. "incorrect password") can leak whether an email address is registered at all — useful to an attacker enumerating valid accounts, not useful to a legitimate user who mistyped their password. The practical rule: be specific and helpful about validation and client-usage errors (malformed input, missing fields, wrong types), and deliberately vaguer about authentication and authorization failures, where precision helps an attacker more than it helps a legitimate user.
Testing that your client actually handles the shape you designed
Once you've settled on an error shape, the thing worth confirming is that your client-side error handling actually reads it correctly — pulls out the field-level detail, surfaces the right message, logs the trace id — rather than falling back to a generic catch-all because the real shape didn't match what the error-handling code assumed. That's easiest to check against a mock that returns your exact designed error shape on demand: a route matched by a specific invalid input, via conditional matching, returning the precise error body your API is supposed to send for that case, so you can confirm the whole path end to end — not just that an error happened, but that your UI shows the specific, useful thing you designed it to show.
Xerat02
Building MockBase.
More from the blog

Your Error Handling Code Has Never Actually Run
Most apps have retry logic, loading states, and fallback UI that's never been triggered by a real failure — because real failures are rare and hard to schedule. Here's how to make them happen on demand.

Idempotency Keys: How to Make "Retry This" Actually Safe
A client that doesn't know whether its request succeeded has one safe option: retry with a key that lets the server recognize "I've already done this." Here's how that actually has to work.