Hoe ontwerp je consistente error-responses en rapporteer je validatiefouten?

Question

IT Interview Practice · Accepted Answer

Een goede error-response doet twee dingen: hij gebruikt de **juiste HTTP-statuscode** (het machineleesbare signaal), en hij retourneert een **consistente, gestructureerde body** waar een ontwikkelaar mee aan de slag kan. Inconsistente error-vormen zijn een van de grootste bronnen van pijn aan clientzijde.

## Gebruik een standaard error-formaat: RFC 7807 (problem+json)

RFC 7807 definieert een standaard "problem details"-body met een eigen media type, zodat elke error in je hele API er hetzelfde uitziet:

```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` — een URI die de errorcategorie identificeert (dereferenceerbaar naar docs).
- `title` — een korte, mensleesbare samenvatting (stabiel per `type`).
- `status` — de HTTP-status, voor het gemak herhaald.
- `detail` — een specifieke uitleg voor *dit* voorval.
- `instance` — op welke request/resource het gebeurde.

## Validatiefouten: rapporteer ze allemaal tegelijk

Voor form-/veldvalidatie, retourneer `422` (of `400`) en een **array van veldfouten** zodat de client elk fout veld in één keer kan markeren — niet één fout tegelijk:

```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" }
  ]
}
```

## Principes

```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
```

## Waarom het belangrijk is

Error-ontwerp is waar API's in de echte wereld stilletjes slagen of falen: het happy path is makkelijk, maar consumers besteden de meeste debugtijd in het error-pad, en een inconsistent of vaag error-contract maakt integratie ellendig. Interviewers checken hiermee twee dingen. Ten eerste, **statuscode plus gestructureerde body die samenwerken** — de status is het grove signaal voor tooling en retries, de body draagt het bruikbare detail — in plaats van het anti-pattern `200 OK` met een error erin. Ten tweede, een **stabiele, machineleesbare errorcode** (via `type` van RFC 7807 of een `code`-veld) zodat clients kunnen vertakken op `"insufficient_funds"` in plaats van string-matchen op een Engelse boodschap die geherformuleerd of gelokaliseerd kan worden. Alle validatiefouten tegelijk retourneren, en nooit interne details zoals stack traces lekken, maakt een antwoord compleet dat laat zien dat je API's hebt gebouwd die andere teams daadwerkelijk moesten gebruiken.

Gebruik een standaard error-formaat: RFC 7807 (problem+json)

Validatiefouten: rapporteer ze allemaal tegelijk

Principes

Waarom het belangrijk is

Gerelateerde vragen