Kako dizajnirati dosljedne error odgovore i prijaviti greške validacije?

Question

IT Interview Practice · Accepted Answer

Dobar error odgovor radi dvije stvari: koristi **ispravan HTTP statusni kod** (strojno čitljiv signal) i vraća **dosljedno, strukturirano tijelo** na koje programer može reagirati. Nedosljedni oblici grešaka jedan su od najvećih izvora boli na strani klijenta.

## Koristite standardni format grešaka: RFC 7807 (problem+json)

RFC 7807 definira standardno "problem details" tijelo s namjenskim media typeom, pa svaka greška u vašem API-ju izgleda isto:

```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` — URI koji identificira kategoriju greške (dereferencibilan do dokumentacije).
- `title` — kratak, ljudski čitljiv sažetak (stabilan po `type`).
- `status` — HTTP status, zrcaljen radi praktičnosti.
- `detail` — specifično objašnjenje za *ovo* pojavljivanje.
- `instance` — na kojem se zahtjevu/resursu dogodilo.

## Greške validacije: prijavite ih sve odjednom

Za validaciju forme/polja, vratite `422` (ili `400`) i **niz grešaka po polju** kako bi klijent mogao istaknuti svako loše polje u jednom prolazu — ne jednu grešku po jednu:

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

## Načela

```text
✓ Isti oblik tijela za svaku grešku (jedan put koda na klijentu)
✓ Stabilan strojno čitljiv kod (type/code) — klijenti granaju po ovome, ne po prozi
✓ Ljudski čitljiva poruka za programere/logove
✗ Nikad ne curite stack traceove, SQL ili interne putanje klijentima
```

## Zašto je to važno

Dizajn grešaka mjesto je gdje API-ji tiho uspijevaju ili propadaju u stvarnom svijetu: sretni put je lak, ali potrošači provode većinu vremena debugiranja na putu grešaka, a nedosljedan ili nejasan ugovor o greškama čini integraciju bijednom. Ispitivači ovim provjeravaju dvije stvari. Prvo, **statusni kod plus strukturirano tijelo koji rade zajedno** — status je grubi signal za alate i ponavljanja, tijelo nosi akcijski detalj — umjesto anti-obrasca `200 OK` s greškom unutra. Drugo, **stabilan, strojno čitljiv kod greške** (preko RFC 7807 `type` ili `code` polja) kako bi klijenti mogli granati po `"insufficient_funds"` umjesto podudaranja engleske poruke koja bi mogla biti preformulirana ili lokalizirana. Vraćanje svih grešaka validacije odjednom i nikad ne curiti interne detalje poput stack traceova zaokružuje odgovor koji pokazuje da ste gradili API-je koje su drugi timovi zaista morali koristiti.

Koristite standardni format grešaka: RFC 7807 (problem+json)

Greške validacije: prijavite ih sve odjednom

Načela

Zašto je to važno

Povezana pitanja