Cum proiectezi răspunsuri de eroare consistente și raportezi erorile de validare?

Question

IT Interview Practice · Accepted Answer

Un răspuns de eroare bun face două lucruri: folosește **status code-ul HTTP corect** (semnalul citibil de mașină) și returnează un **body structurat și consistent** pe care un dezvoltator îl poate acționa. Formele de eroare inconsistente sunt una dintre cele mai mari surse de durere de partea clientului.

## Folosește un format standard de eroare: RFC 7807 (problem+json)

RFC 7807 definește un body standard „problem details" cu un media type dedicat, așa că fiecare eroare din API-ul tău arată la fel:

```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 care identifică categoria erorii (dereferențiabil către documentație).
- `title` — un rezumat scurt, citibil de om (stabil per `type`).
- `status` — status-ul HTTP, oglindit pentru comoditate.
- `detail` — o explicație specifică pentru *această* apariție.
- `instance` — pe ce cerere/resursă s-a întâmplat.

## Erori de validare: raportează-le pe toate deodată

Pentru validarea de formular/câmp, returnează `422` (sau `400`) și un **array de erori pe câmp**, ca clientul să poată evidenția fiecare câmp greșit dintr-o singură trecere — nu câte o eroare pe rând:

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

## Principii

```text
✓ Aceeași formă de body pentru fiecare eroare (o singură cale de cod pe client)
✓ Un cod stabil, citibil de mașină (type/code) — clienții ramifică pe acesta, nu pe proză
✓ Mesaj citibil de om pentru dezvoltatori/log-uri
✗ Nu expune niciodată stack trace-uri, SQL sau căi interne clienților
```

## De ce contează

Designul erorilor este locul unde API-urile reușesc sau eșuează în tăcere în lumea reală: calea fericită este ușoară, dar consumatorii petrec cea mai mare parte a timpului de debugging pe calea de eroare, iar un contract de eroare inconsistent sau vag face integrarea mizerabilă. Intervievatorii folosesc asta pentru a verifica două lucruri. În primul rând, **status code plus body structurat lucrând împreună** — status-ul este semnalul grosier pentru tooling și retry-uri, body-ul poartă detaliul acționabil — mai degrabă decât anti-pattern-ul `200 OK` cu o eroare înăuntru. În al doilea rând, un **cod de eroare stabil, citibil de mașină** (prin `type` din RFC 7807 sau un câmp `code`), ca clienții să poată ramifica pe `"insufficient_funds"` în loc să facă string-matching pe un mesaj în engleză care ar putea fi reformulat sau localizat. Returnarea tuturor erorilor de validare deodată și nescurgerea niciodată a detaliilor interne precum stack trace-urile completează un răspuns care arată că ai construit API-uri pe care alte echipe chiar au trebuit să le consume.

Folosește un format standard de eroare: RFC 7807 (problem+json)

Erori de validare: raportează-le pe toate deodată

Principii

De ce contează

Întrebări conexe