API hatalarını uçtan uca nasıl tasarlarsınız? Backend'den dönen hataları frontend'de kullanıcıya nasıl gösterirsiniz?

İyi bir hata tasarımı üç şey sağlar: tutarlı bir hata formatı, doğru HTTP durum kodu ve makinenin okuyabileceği bir hata kodu. Böylece frontend her hata için mesaj metnini parse etmek zorunda kalmaz ve geliştirici hatayı loglarda kolayca bulur.

Standart format: RFC 9457 (Problem Details)

{
  "type": "https://api.ornek.com/errors/insufficient-stock",
  "title": "Yetersiz stok",
  "status": 409,
  "code": "INSUFFICIENT_STOCK",
  "detail": "Seçtiğiniz üründen sadece 2 adet kaldı.",
  "errors": { "quantity": ["En fazla 2 olabilir"] },
  "requestId": "a1b2c3"
}

Backend kuralları

• 4xx istemci hatası, 5xx sunucu hatasıdır; validasyon için 400/422, yetki için 401/403, çakışma için 409.
• Tüm hatalar tek bir global error handler'dan geçer; beklenmeyen hatalarda stack trace kullanıcıya gönderilmez, sadece loglanır.
• Her yanıtta requestId olur; kullanıcı destek ekibine bunu iletirse log anında bulunur.

app.use((err, req, res, next) => {
  const status = err.status ?? 500;
  if (status >= 500) logger.error({ err, reqId: req.id });
  res.status(status).type("application/problem+json").json({
    title: status >= 500 ? "Beklenmeyen bir hata oluştu" : err.message,
    status, code: err.code ?? "INTERNAL", errors: err.fieldErrors, requestId: req.id,
  });
});

Frontend kuralları

• Alan hataları (errors) formdaki ilgili input'un altında gösterilir.
• İş kuralı hataları (code) için kullanıcı dostu ve çevrilebilir mesaj: INSUFFICIENT_STOCK -> "Stok yetersiz".
• 401 -> token yenile veya login'e yönlendir; 403 -> "yetkiniz yok" ekranı; 404 -> bulunamadı sayfası.
• 5xx ve ağ hataları -> genel mesaj + "Tekrar dene" butonu; GET istekleri için otomatik retry (exponential backoff), POST için retry sadece idempotency key varsa.
• React'te beklenmeyen render hataları Error Boundary ile, API hataları ise veri katmanında (TanStack Query onError) merkezi ele alınır.