How do you design consistent error responses and report validation errors?

Question

IT Interview Practice · Accepted Answer

A good error response does two things: it uses the **right HTTP status code** (the machine-readable signal), and it returns a **consistent, structured body** that a developer can act on. Inconsistent error shapes are one of the biggest sources of client-side pain.

## Use a standard error format: RFC 7807 (problem+json)

RFC 7807 defines a standard "problem details" body with a dedicated media type, so every error across your API looks the same:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — a URI identifying the error category (dereferenceable to docs).
- `title` — a short, human-readable summary (stable per `type`).
- `status` — the HTTP status, mirrored for convenience.
- `detail` — a specific explanation for *this* occurrence.
- `instance` — which request/resource it happened on.

## Validation errors: report them all at once

For form/field validation, return `422` (or `400`) and an **array of field errors** so the client can highlight every bad field in one pass — not one error at a time:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Principles

```text
✓ Same body shape for every error (one code path on the client)
✓ A stable machine-readable code (type/code) — clients branch on this, not on prose
✓ Human-readable message for developers/logs
✗ Never leak stack traces, SQL, or internal paths to clients
```

## Why it matters

Error design is where APIs quietly succeed or fail in the real world: the happy path is easy, but consumers spend most of their debugging time in the error path, and an inconsistent or vague error contract makes integration miserable. Interviewers use this to check for two things. First, **status code plus structured body working together** — the status is the coarse signal for tooling and retries, the body carries the actionable detail — rather than the anti-pattern of `200 OK` with an error inside. Second, a **stable, machine-readable error code** (via RFC 7807's `type` or a `code` field) so clients can branch on `"insufficient_funds"` rather than string-matching an English message that might be reworded or localized. Returning all validation errors at once, and never leaking internal details like stack traces, rounds out an answer that shows you've built APIs other teams actually had to consume.

Use a standard error format: RFC 7807 (problem+json)

Validation errors: report them all at once

Principles

Why it matters

Related questions