Miten suunnittelet johdonmukaiset error responset ja raportoit validointivirheet?

Question

IT Interview Practice · Accepted Answer

Hyvä error response tekee kaksi asiaa: se käyttää **oikeaa HTTP status codea** (koneluettava signaali) ja palauttaa **johdonmukaisen, jäsennellyn bodyn**, jonka mukaan kehittäjä voi toimia. Epäjohdonmukaiset virhemuodot ovat yksi suurimmista client-puolen tuskan lähteistä.

## Käytä standardia virhemuotoa: RFC 7807 (problem+json)

RFC 7807 määrittelee standardin "problem details" -bodyn omalla media typellään, joten jokainen virhe API:ssasi näyttää samalta:

```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, joka tunnistaa virheluokan (dereferoitavissa dokumentaatioon).
- `title` — lyhyt, ihmisluettava yhteenveto (vakaa per `type`).
- `status` — HTTP-status, toistettuna mukavuuden vuoksi.
- `detail` — tarkka selitys *tälle* tapahtumalle.
- `instance` — mihin pyyntöön/resurssiin se tapahtui.

## Validointivirheet: raportoi ne kaikki kerralla

Lomake-/kenttävalidoinnille palauta `422` (tai `400`) ja **taulukko kenttävirheitä**, jotta client voi korostaa jokaisen virheellisen kentän yhdellä kertaa — ei yhtä virhettä kerrallaan:

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

## Periaatteet

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

## Miksi se on tärkeää

Virhesuunnittelu on paikka, jossa API:t hiljaa onnistuvat tai epäonnistuvat todellisessa maailmassa: happy path on helppo, mutta kuluttajat viettävät suurimman osan debuggausajastaan virhepolulla, ja epäjohdonmukainen tai epämääräinen virhesopimus tekee integraatiosta kurjaa. Haastattelijat käyttävät tätä tarkistaakseen kaksi asiaa. Ensinnäkin, **status code plus jäsennelty body toimivat yhdessä** — status on karkea signaali työkalutukselle ja retryille, body kantaa toteutettavan yksityiskohdan — eikä anti-patternia `200 OK` virheen ollessa sisällä. Toiseksi, **vakaa, koneluettava virhekoodi** (RFC 7807:n `type`in tai `code`-kentän kautta), jotta clientit voivat haarautua koodin `"insufficient_funds"` mukaan sen sijaan että täsmäisivät englanninkielistä viestiä, joka saatetaan uudelleensanoittaa tai lokalisoida. Kaikkien validointivirheiden palauttaminen kerralla ja sisäisten yksityiskohtien kuten stack tracejen koskaan vuotamatta jättäminen täydentää vastauksen, joka osoittaa, että olet rakentanut API:ja, joita muiden tiimien piti oikeasti käyttää.

Käytä standardia virhemuotoa: RFC 7807 (problem+json)

Validointivirheet: raportoi ne kaikki kerralla

Periaatteet

Miksi se on tärkeää

Aiheeseen liittyvät kysymykset