Tutarlı error response'ları nasıl tasarlar ve validation hatalarını nasıl raporlarsınız?

Question

IT Interview Practice · Accepted Answer

İyi bir error response iki şey yapar: **doğru HTTP status code'unu** (makine tarafından okunabilir sinyal) kullanır ve bir geliştiricinin üzerine işlem yapabileceği **tutarlı, yapılandırılmış bir body** döndürür. Tutarsız hata biçimleri, client tarafındaki acının en büyük kaynaklarından biridir.

## Standart bir hata formatı kullanın: RFC 7807 (problem+json)

RFC 7807, özel bir media type ile standart bir "problem details" body'si tanımlar, böylece API'nizdeki her hata aynı görünür:

```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` — hata kategorisini tanımlayan bir URI (docs'a dereference edilebilir).
- `title` — kısa, insan tarafından okunabilir bir özet (her `type` için sabit).
- `status` — kolaylık için yansıtılan HTTP status.
- `detail` — *bu* olay için özel bir açıklama.
- `instance` — hangi request/resource üzerinde gerçekleştiği.

## Validation hataları: hepsini bir kerede raporlayın

Form/field validation için `422` (ya da `400`) ve bir **field hataları dizisi** döndürün, böylece client her hatalı alanı tek seferde vurgulayabilir — her seferde tek bir hata değil:

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

## İlkeler

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

## Neden önemli

Hata tasarımı, API'lerin gerçek dünyada sessizce başarılı ya da başarısız olduğu yerdir: happy path kolaydır, ama tüketiciler debug zamanlarının çoğunu hata yolunda geçirir ve tutarsız ya da belirsiz bir hata sözleşmesi entegrasyonu içinden çıkılmaz kılar. Mülakatçılar bunu iki şey için kontrol eder. Birincisi, **status code artı yapılandırılmış body'nin birlikte çalışması** — status, araçlar ve retry'lar için kaba sinyaldir, body ise üzerine işlem yapılabilir ayrıntıyı taşır — içinde hata olan `200 OK` anti-pattern'i yerine. İkincisi, **kararlı, makine tarafından okunabilir bir hata kodu** (RFC 7807'nin `type`'ı ya da bir `code` alanı aracılığıyla), böylece client'lar yeniden yazılabilecek ya da yerelleştirilebilecek bir İngilizce mesajı string eşleştirmek yerine `"insufficient_funds"`'a göre dallanabilir. Tüm validation hatalarını bir kerede döndürmek ve stack trace gibi iç ayrıntıları asla sızdırmamak, başka ekiplerin gerçekten kullanmak zorunda kaldığı API'ler kurduğunuzu gösteren bir cevabı tamamlar.

Standart bir hata formatı kullanın: RFC 7807 (problem+json)

Validation hataları: hepsini bir kerede raporlayın

İlkeler

Neden önemli

İlgili sorular