Unabunije error responses zinazolingana na kuripoti validation errors?

Question

IT Interview Practice · Accepted Answer

Error response nzuri hufanya mambo mawili: hutumia **HTTP status code sahihi** (ishara inayosomeka na mashine), na hurudisha **body yenye muundo na inayolingana** ambayo developer anaweza kuichukulia hatua. Maumbo ya error yasiyolingana ni mojawapo ya vyanzo vikubwa zaidi vya maumivu ya upande wa client.

## Tumia muundo wa kawaida wa error: RFC 7807 (problem+json)

RFC 7807 hufafanua body ya kawaida ya "problem details" yenye media type maalum, ili kila error katika API yako ionekane sawa:

```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 inayotambua kundi la error (inayoweza ku-dereference kwenda docs).
- `title` — muhtasari mfupi, unaosomeka na binadamu (thabiti kwa kila `type`).
- `status` — HTTP status, iliyorudiwa kwa urahisi.
- `detail` — maelezo mahususi kwa tukio *hili*.
- `instance` — request/rasilimali gani ilipotokea.

## Validation errors: ziripoti zote kwa mara moja

Kwa validation ya form/field, rudisha `422` (au `400`) na **array ya field errors** ili client iweze kuangazia kila field mbaya kwa pigo moja — si error moja kwa wakati:

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

## Kanuni

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

## Kwa nini ni muhimu

Usanifu wa error ndipo APIs hufanikiwa au kushindwa kimyakimya katika ulimwengu halisi: happy path ni rahisi, lakini watumiaji hutumia muda wao mwingi wa ku-debug katika njia ya error, na mkataba wa error usiolingana au usio wazi hufanya integration kuwa taabu. Wahoji hutumia hili kuangalia mambo mawili. Kwanza, **status code pamoja na body yenye muundo zikifanya kazi pamoja** — status ni ishara mbaya kwa tooling na retries, body hubeba undani unaoweza kuchukuliwa hatua — badala ya anti-pattern ya `200 OK` na error ndani. Pili, **error code thabiti, inayosomeka na mashine** (kupitia `type` ya RFC 7807 au field ya `code`) ili clients ziweze kutawi kwa `"insufficient_funds"` badala ya kulinganisha string ya ujumbe wa Kiingereza unaoweza kubadilishwa maneno au ku-localized. Kurudisha validation errors zote kwa mara moja, na kutovujisha kamwe undani wa ndani kama stack traces, hukamilisha jibu linaloonyesha umejenga APIs ambazo timu nyingine zililazimika kuzitumia kweli.

Tumia muundo wa kawaida wa error: RFC 7807 (problem+json)

Validation errors: ziripoti zote kwa mara moja

Kanuni

Kwa nini ni muhimu

Maswali yanayohusiana