Jak projektować spójne odpowiedzi błędów i zgłaszać błędy walidacji?

Question

IT Interview Practice · Accepted Answer

Dobra odpowiedź błędu robi dwie rzeczy: używa **właściwego kodu statusu HTTP** (sygnału odczytywalnego maszynowo) i zwraca **spójne, ustrukturyzowane ciało**, na które programista może zareagować. Niespójne kształty błędów to jedno z największych źródeł bólu po stronie klienta.

## Używaj standardowego formatu błędu: RFC 7807 (problem+json)

RFC 7807 definiuje standardowe ciało „problem details" z dedykowanym media type, więc każdy błąd w Twoim API wygląda tak samo:

```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 identyfikujący kategorię błędu (dereferencjowalny do dokumentacji).
- `title` — krótkie, czytelne dla człowieka podsumowanie (stabilne dla danego `type`).
- `status` — status HTTP, powtórzony dla wygody.
- `detail` — konkretne wyjaśnienie dla *tego* wystąpienia.
- `instance` — na którym żądaniu/zasobie to się zdarzyło.

## Błędy walidacji: zgłaszaj je wszystkie naraz

Dla walidacji formularza/pól zwróć `422` (lub `400`) i **tablicę błędów pól**, by klient mógł podświetlić każde błędne pole za jednym razem — a nie jeden błąd na raz:

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

## Zasady

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

## Dlaczego to ważne

Projektowanie błędów to miejsce, gdzie API po cichu odnoszą sukces lub porażkę w prawdziwym świecie: happy path jest łatwy, ale konsumenci spędzają większość czasu na debugowaniu w ścieżce błędu, a niespójny lub mglisty kontrakt błędu czyni integrację udręką. Rozmówcy używają tego, by sprawdzić dwie rzeczy. Po pierwsze, **kod statusu i ustrukturyzowane ciało współpracujące ze sobą** — status to zgrubny sygnał dla narzędzi i ponawiania, ciało niesie szczegóły do działania — zamiast anty-wzorca `200 OK` z błędem w środku. Po drugie, **stabilny, odczytywalny maszynowo kod błędu** (przez `type` z RFC 7807 lub pole `code`), by klienci mogli rozgałęziać się na `"insufficient_funds"`, a nie dopasowywać angielski komunikat, który może zostać przeredagowany lub zlokalizowany. Zwracanie wszystkich błędów walidacji naraz i nigdy nieujawnianie wewnętrznych szczegółów jak stack trace dopełnia odpowiedzi pokazującej, że budowałeś API, które inne zespoły faktycznie musiały konsumować.

Używaj standardowego formatu błędu: RFC 7807 (problem+json)

Błędy walidacji: zgłaszaj je wszystkie naraz

Zasady

Dlaczego to ważne

Powiązane pytania