Jak navrhnete konzistentní chybové odpovědi a hlásíte validační chyby?

Question

IT Interview Practice · Accepted Answer

Dobrá chybová odpověď dělá dvě věci: používá **správný HTTP status kód** (strojově čitelný signál) a vrací **konzistentní, strukturované tělo**, se kterým může vývojář pracovat. Nekonzistentní tvary chyb jsou jedním z největších zdrojů utrpení na straně klienta.

## Používejte standardní formát chyb: RFC 7807 (problem+json)

RFC 7807 definuje standardní tělo „problem details“ s vyhrazeným media typem, takže každá chyba napříč vaším API vypadá stejně:

```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 identifikující kategorii chyby (dereferencovatelné na dokumentaci).
- `title` — krátké, člověku čitelné shrnutí (stabilní pro každý `type`).
- `status` — HTTP status, zrcadlený pro pohodlí.
- `detail` — konkrétní vysvětlení pro *tento* výskyt.
- `instance` — na kterém požadavku/zdroji k tomu došlo.

## Validační chyby: hlaste je všechny najednou

Pro validaci formuláře/polí vraťte `422` (nebo `400`) a **pole chyb podle polí (field errors)**, aby klient mohl zvýraznit každé chybné pole naráz — ne jednu chybu po druhé:

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

## Zásady

```text
✓ Stejný tvar těla pro každou chybu (jedna větev kódu na klientovi)
✓ Stabilní strojově čitelný kód (type/code) — klienti větví podle něj, ne podle prózy
✓ Člověku čitelná zpráva pro vývojáře/logy
✗ Nikdy neposílejte klientům stack trace, SQL ani interní cesty
```

## Proč je to důležité

Návrh chyb je místo, kde API v reálném světě tiše uspějí nebo selžou: happy path je snadná, ale konzumenti tráví většinu času laděním v chybové cestě, a nekonzistentní nebo vágní kontrakt chyb dělá integraci utrpením. Tazatelé tím ověřují dvě věci. Zaprvé, **status kód a strukturované tělo fungující společně** — status je hrubý signál pro nástroje a opakování, tělo nese akční detail — místo anti-vzoru `200 OK` s chybou uvnitř. Zadruhé, **stabilní, strojově čitelný kód chyby** (přes `type` z RFC 7807 nebo pole `code`), aby klienti mohli větvit podle `"insufficient_funds"` místo porovnávání řetězce anglické zprávy, která může být přeformulována nebo lokalizována. Vrácení všech validačních chyb najednou a nikdy neúnik interních detailů jako stack trace dotváří odpověď, která ukazuje, že jste stavěli API, jež jiné týmy skutečně musely konzumovat.

Používejte standardní formát chyb: RFC 7807 (problem+json)

Validační chyby: hlaste je všechny najednou

Zásady

Proč je to důležité

Související otázky