Hogyan tervezel konzisztens error response-okat, és hogyan jelentesz validációs hibákat?

Question

IT Interview Practice · Accepted Answer

Egy jó error response két dolgot tesz: a **helyes HTTP status code**-ot használja (a gép által olvasható jelzést), és egy **konzisztens, strukturált body**-t ad vissza, amivel egy fejlesztő dolgozni tud. A következetlen hibaformátumok az egyik legnagyobb forrása a kliensoldali szenvedésnek.

## Használj standard hibaformátumot: RFC 7807 (problem+json)

Az RFC 7807 egy standard "problem details" body-t definiál egy dedikált media type-pal, így az API-d minden hibája ugyanúgy néz ki:

```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` — a hibakategóriát azonosító URI (dokumentációra dereferálható).
- `title` — rövid, ember által olvasható összefoglaló (stabil `type`-onként).
- `status` — a HTTP status, kényelmi okból megismételve.
- `detail` — konkrét magyarázat *erre* az előfordulásra.
- `instance` — melyik kérésen/erőforráson történt.

## Validációs hibák: jelentsd mind egyszerre

Form-/mező-validációhoz adj vissza `422`-t (vagy `400`-at) és egy **mezőhibák tömbjét**, hogy a kliens egy menetben kiemelhesse az összes hibás mezőt — ne egyesével:

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

## Alapelvek

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

## Miért fontos

A hibatervezés az, ahol az API-k csendben sikeresek vagy elbuknak a való világban: a happy path könnyű, de a felhasználók a debuggolási idejük nagy részét a hibaágban töltik, és egy következetlen vagy homályos hibaszerződés nyomorúságossá teszi az integrációt. Az interjúztatók ezzel két dolgot ellenőriznek. Először, **a status code és a strukturált body együttműködése** — a status a durva jelzés a toolingnak és a retry-oknak, a body hordozza a cselekvésre alkalmas részletet — a `200 OK`-val hibát tartalmazó anti-pattern helyett. Másodszor, egy **stabil, gép által olvasható hibakód** (az RFC 7807 `type`-ján vagy egy `code` mezőn keresztül), hogy a kliensek az `"insufficient_funds"` alapján ágazhassanak el, ahelyett, hogy egy angol üzenetre illesztenének stringet, amelyet átfogalmazhatnak vagy lokalizálhatnak. Az összes validációs hiba egyszerre való visszaadása, és a belső részletek, például stack trace-ek soha ki nem szivárogtatása kerekíti le a választ, amely megmutatja, hogy olyan API-kat építettél, amelyeket más csapatoknak ténylegesen használniuk kellett.

Használj standard hibaformátumot: RFC 7807 (problem+json)

Validációs hibák: jelentsd mind egyszerre

Alapelvek

Miért fontos

Kapcsolódó kérdések