Hata Formatı

Kaza Rehberi API’sinde her hata yanıtı aynı gövde biçimini kullanır:

{
  "hata": {
    "kod": "GIRDI_GECERSIZ",
    "mesaj": "İstek doğrulanamadı"
  }
}

Bu format kod tarafında hataGovdesi(kod, mesaj) yardımcı fonksiyonuyla üretilir ve AppError sınıfı üzerinden fırlatılır:

export class AppError extends Error {
  constructor(
    public kod: string,
    public mesaj: string,
    public durum: ContentfulStatusCode = 400,
  ) { super(mesaj); }
}

Merkezi hata işleyici

Uygulama genelinde tek bir onError işleyicisi çalışır:

AppError fırlatılırsa → tanımlı durum (HTTP status) + {hata:{kod,mesaj}} döner.
Beklenmeyen (programlama) hatalarında → sunucu loguna JSON detay yazılır, hata raportörüne (Sentry varsa) iletilir, istemciye iç detay SIZDIRILMAZ: sabit 500 SUNUCU_HATASI + jenerik mesaj döner.
Eşleşmeyen route → 404 BULUNAMADI.

Yaygın hata kodları

Kod	HTTP durumu	Anlamı
`GIRDI_GECERSIZ`	400	İstek gövdesi/sorgu parametreleri zod şemasını doğrulayamadı
`TOKEN_GECERSIZ`	401	Bearer/cookie token yok, geçersiz veya süresi dolmuş
`YETKI_YOK`	403	Kimlik doğrulandı ama rol/izin yetersiz (RBAC-lite)
`ORIGIN_REDDEDILDI`	403	Cookie tabanlı, state-değiştiren istek allowlist dışı bir `Origin`’den geldi
`BULUNAMADI`	404	Kayıt ya da uç bulunamadı
`SUNUCU_HATASI`	500	Beklenmeyen sunucu hatası veya eksik yapılandırma (örn. DB/JWT_SECRET tanımsız)

Örnek: 401 yanıtı

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "hata": {
    "kod": "TOKEN_GECERSIZ",
    "mesaj": "Oturum geçersiz veya süresi dolmuş"
  }
}

Örnek: 403 yanıtı (izin yetersiz)

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "hata": {
    "kod": "YETKI_YOK",
    "mesaj": "Bu işlem için yetkiniz yok"
  }
}