MediumExperience level: 3-5 years · 8-15 years1 min read

How do you design consistent, useful API error responses?

Reviewed by Gurusankar M.

Asked inAmazonMicrosoftDeloitteCognizant
#error handling#problem details#rfc 7807#status codes#api design
Report issue

Short Answer

Use correct HTTP status codes plus a consistent machine-readable error body (RFC 7807 Problem Details: type, title, status, detail, instance, plus a stable error code and field-level validation errors). Never leak stack traces; include a correlation id for support.

On this page

Concept Made Simple

Coffee Chat Question

“How do you design consistent, useful API error responses?”

Remember It Faster

Mind Map Answer

Status code
right 4xx/5xx
Body (RFC 7807)
type/title/status/detail
Add
stable error code + field errors + traceId
Never
stack traces / internal details

Learn by Doing

Hands-on Keyboard

json
{
  "type": "https://api.x.com/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "code": "ORDER_INVALID",
  "errors": [{ "field": "amount", "message": "must be > 0" }],
  "traceId": "abc-123"
}

Think Beyond the Expected

What If?

Why is a stable machine-readable 'error code' better than relying on the HTTP status alone?

Many distinct failures map to the same status (400 covers dozens of validation errors). A stable code (ORDER_INVALID) lets clients branch logic and lets you change wording without breaking them — the status says the category, the code says the exact reason.

Real World

Inconsistent error shapes across endpoints are a top API-consumer complaint; standardizing on RFC 7807 + stable error codes + a correlation id (for log lookup) is the enterprise norm.

Interviewer's Expectation

Keywords they're listening for:

  • correct status codes
  • RFC 7807 / consistent body
  • stable error codes
  • field-level validation errors
  • correlation id, no stack traces

Common Mistakes

  • Leaking stack traces / internal messages
  • Inconsistent error shapes per endpoint
  • Using 200 with an error in the body

Best Practices

  • Adopt RFC 7807 + stable error codes
  • Centralize mapping (@ControllerAdvice)
  • Always include a traceId; never leak internals

Follow-up Questions

  1. How do field-level validation errors look?
  2. Why include a correlation/trace id?
  3. Where do you centralize error mapping (e.g. @ControllerAdvice)?

Continue Learning with AI

Take this question deeper with your favourite AI assistant. Pick a depth, copy the prompt, or open it directly — AI is your learning companion, not a shortcut.

Plain-language foundations

I'm preparing for a software engineering interview and want to understand this from scratch, as a beginner.

Topic: Status Codes (REST APIs)
Interview question: "How do you design consistent, useful API error responses?"

Please:
1. Explain the core idea in simple, plain language, using an everyday analogy.
2. Define any technical terms you use.
3. Walk through one small, concrete example.
4. Finish with a single sentence I can easily remember.

Keep the tone friendly and assume I'm new to this topic.
Open inChatGPTGeminiClaude

Was this answer helpful?

Affiliate links

Tools for Your Developer Workspace

Equipment for a comfortable, productive setup.

As an Amazon Associate I earn from qualifying purchases.