Kako zasnujete dosledne error responses in poročate o napakah validacije?

Question

IT Interview Practice · Accepted Answer

Dober error response naredi dvoje: uporabi **pravo status kodo HTTP** (strojno berljiv signal) in vrne **dosledno, strukturirano telo (body)**, na katerega se razvijalec lahko odzove. Nedosledne oblike napak so eden največjih virov bolečine na strani odjemalca.

## Uporabite standardno obliko napake: RFC 7807 (problem+json)

RFC 7807 definira standardno telo "problem details" z namenskim media type, tako da vsaka napaka v vašem API-ju izgleda enako:

```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, ki identificira kategorijo napake (razrešljiv do dokumentacije).
- `title` — kratek, človeku berljiv povzetek (stabilen na `type`).
- `status` — status HTTP, podvojen za priročnost.
- `detail` — konkretna razlaga za *to* pojavitev.
- `instance` — na kateri zahtevi/viru se je zgodila.

## Napake validacije: sporočite vse naenkrat

Za validacijo obrazcev/polj vrnite `422` (ali `400`) in **polje napak po poljih**, da odjemalec v enem prehodu osvetli vsako slabo polje — ne po eno napako naenkrat:

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

## Zakaj je to pomembno

Zasnova napak je mesto, kjer API v resničnem svetu tiho uspe ali propade: srečna pot je enostavna, a uporabniki večino časa razhroščevanja preživijo na poti napak, nedosledna ali nejasna pogodba o napakah pa naredi integracijo bedno. Spraševalci s tem preverijo dvoje. Prvič, **status koda in strukturirano telo, ki delujeta skupaj** — status je grob signal za orodja in ponovne poskuse, telo pa nosi uporaben detajl — namesto antivzorca `200 OK` z napako znotraj. Drugič, **stabilna, strojno berljiva koda napake** (prek `type` iz RFC 7807 ali polja `code`), da lahko odjemalci vejejo na `"insufficient_funds"` namesto ujemanja niza angleškega sporočila, ki se lahko preoblikuje ali lokalizira. Vračanje vseh napak validacije naenkrat in nikoli razkrivanje notranjih podrobnosti, kot so stack traci, zaokroži odgovor, ki pokaže, da ste gradili API-je, ki so jih morale dejansko uporabljati druge ekipe.

Uporabite standardno obliko napake: RFC 7807 (problem+json)

Napake validacije: sporočite vse naenkrat

Načela

Zakaj je to pomembno

Povezana vprašanja