Skip to content
API Design Learn/Querying, Errors & Contracts
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Errors That Help Instead of Hurt

3 min read

You'll learn to

  • -Return an error body in one standard shape (RFC 7807 Problem Details) that code can read
  • -Report every failing field at once, and count the requests it saves the client
  • -Keep internal detail, such as stack traces, out of what the client sees

Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.

A status code tells a client the category of failure. The body is where the API says what went wrong and, ideally, how to fix it. Every API that grows beyond a handful of endpoints eventually needs one consistent error shape, and the only question is whether it is designed on purpose or accumulates by accident, one different format per endpoint.

An Analogy: The Doctor's Note vs. "You Are Unwell"

"You are unwell" is true and useless. A good doctor's note says what is wrong, how serious it is, and what to do. And if three things are wrong, a good doctor says all three at once, not one per visit. An error response should work the same way.

RFC 7807: Problem Details for HTTP APIs

An RFC (request for comments) is a published internet standard or proposal. RFC 7807 defines a standard JSON shape for errors, so the same client code can read errors from any endpoint.

A standardized, machine-parseable error shape (RFC 7807)
{
  "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 category of error. Code can match on it without parsing human-readable text.
  • -title: a short human-readable summary of the category, the same every time this error occurs.
  • -status: the HTTP status code, repeated in the body for when the body is logged on its own.
  • -detail: a human-readable explanation of this particular occurrence.
  • -instance: a URI naming this specific occurrence, useful for tracing a support case.

The value is consistency. Client error-handling code is written once, against type and status, instead of once per endpoint. It is the same "consistency removes friction" idea as resource naming, applied to failures.

Field-Level Validation Errors

Actionable, field-specific 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"}
  ]
}

An error that only says "invalid input" forces the client, and the person debugging, to guess which field and which rule failed. Returning every failing field at once lets the client fix everything in one go. The demo counts the difference for a body with two mistakes.

Press Run: 3 requests when errors arrive one at a time, 2 when they all arrive together

Never leak internals into a client-visible error: a stack trace, a raw database constraint name or a file path in detail is both a security exposure and useless to a caller who cannot act on it.

Interview Signal

A validation error currently returns {"error": "invalid request"} with no further detail. The interviewer asks how you'd improve it.

Weak Answer

"I'd just make the message more descriptive, like 'invalid request - please check your input.'"

Strong Answer

"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."

Check Yourself1 / 5

What is the benefit of standardizing error responses on a shape like RFC 7807 Problem Details?

Ready to Build This?

Design The Error Whisperer in the API Design Lab's REST Foundations act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!