Come progetti risposte di errore coerenti e riporti gli errori di validazione?

Question

IT Interview Practice · Accepted Answer

Una buona risposta di errore fa due cose: usa il **codice di stato HTTP corretto** (il segnale leggibile dalla macchina), e restituisce un **body strutturato e coerente** su cui uno sviluppatore può agire. Forme di errore incoerenti sono una delle maggiori fonti di dolore lato client.

## Usa un formato di errore standard: RFC 7807 (problem+json)

RFC 7807 definisce un body "problem details" standard con un media type dedicato, così ogni errore nella tua API appare uguale:

```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` — un URI che identifica la categoria di errore (dereferenziabile alla documentazione).
- `title` — un breve riepilogo leggibile dall'uomo (stabile per ogni `type`).
- `status` — lo status HTTP, rispecchiato per comodità.
- `detail` — una spiegazione specifica per *questa* occorrenza.
- `instance` — su quale richiesta/risorsa è avvenuto.

## Errori di validazione: riportali tutti in una volta

Per la validazione di form/campi, restituisci `422` (o `400`) e un **array di errori per campo** così che il client possa evidenziare ogni campo errato in un solo passaggio — non un errore alla volta:

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

## Principi

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

## Perché è importante

Il design degli errori è dove le API silenziosamente riescono o falliscono nel mondo reale: l'happy path è facile, ma i consumatori passano la maggior parte del loro tempo di debug nel percorso d'errore, e un contratto d'errore incoerente o vago rende l'integrazione miserabile. Gli intervistatori lo usano per verificare due cose. Primo, **status code e body strutturato che lavorano insieme** — lo status è il segnale grezzo per tooling e retry, il body porta il dettaglio azionabile — anziché l'anti-pattern di `200 OK` con un errore dentro. Secondo, un **codice d'errore stabile e leggibile dalla macchina** (tramite il `type` di RFC 7807 o un campo `code`) così che i client possano ramificare su `"insufficient_funds"` anziché fare string-matching su un messaggio in inglese che potrebbe essere riscritto o localizzato. Restituire tutti gli errori di validazione in una volta, e non far mai trapelare dettagli interni come gli stack trace, completa una risposta che mostra che hai costruito API che altri team hanno davvero dovuto consumare.

Usa un formato di errore standard: RFC 7807 (problem+json)

Errori di validazione: riportali tutti in una volta

Principi

Perché è importante

Domande correlate