Bir API’nin başarılı cevapları genellikle özenle tasarlanır.

Hata cevapları ise zamanla birikir.

Bir endpoint şunu döndürür:

{ "error": "User not found" }

Bir diğeri:

{ "message": "Validation failed", "code": 1003 }

Üçüncüsü HTML bir hata sayfası döner, çünkü exception framework seviyesine kadar çıkmıştır.

Client geliştiricisi her biri için ayrı parse kodu yazar.

Problem Details

RFC 9457, HTTP API’lerinde hata cevapları için ortak bir format tanımlıyor. Daha önceki RFC 7807’nin güncellenmiş hali.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/insufficient-funds",
  "title": "Yetersiz bakiye",
  "status": 422,
  "detail": "Hesap bakiyesi 30 TL, işlem tutarı 50 TL.",
  "instance": "/transfers/8812"
}

type: Hatanın türünü tanımlayan bir URI. Client’ın programatik olarak kontrol edeceği alan budur.

title: Hata türünün insan tarafından okunabilir kısa açıklaması. Aynı type için hep aynıdır.

detail: Bu özel duruma ait açıklama.

instance: Hatanın oluştuğu kaynağa veya isteğe referans.

Bunların yanına hataya özel alanlar eklenebilir. Yukarıdaki örnekte balance ve amount alanları eklemek, client’ın kullanıcıya daha iyi bir mesaj göstermesini sağlar.

Spring 6 ile ProblemDetail sınıfı framework’e yerleşik geldi. spring.mvc.problemdetails.enabled=true ile framework’ün kendi hataları da bu formatta dönmeye başlıyor.

Mesaja göre karar verilmemeli

Client’ların hata mesajı metnine göre karar vermesi sık görülen bir hata:

if (error.message.includes("not found")) ...

Mesaj değiştirildiğinde veya çevrildiğinde client kırılır.

Programatik kararlar için sabit bir tanımlayıcı gerekir. Problem Details’te bu type alanıdır. Sabit, belgelenmiş ve değişmeyen bir değer.

Doğrulama hataları

Form doğrulama hatalarında birden fazla alan aynı anda hatalı olabilir. Bunları tek bir mesajda birleştirmek client’ın işini zorlaştırır:

"detail": "email geçersiz, password çok kısa"

Alan bazında bir liste daha kullanışlıdır:

"errors": [
  { "field": "email", "code": "invalid_format" },
  { "field": "password", "code": "too_short", "min": 8 }
]

Client her hatayı ilgili form alanının altında gösterebilir. code alanı sayesinde mesajları kendi dilinde üretebilir.

Status code doğru seçilmeli

Her hatayı 400 veya 500 ile dönmek, client’ın en temel ayrımı yapmasını engeller.

Kabaca:

  • 400: İstek bozuk, parse edilemiyor.
  • 401: Kimlik doğrulanmamış.
  • 403: Kimlik doğru ama yetki yok.
  • 404: Kaynak yok.
  • 409: Mevcut durumla çakışma.
  • 422: İstek anlaşılır ama iş kuralına uymuyor.
  • 429: Çok fazla istek.

4xx client’ın düzeltmesi gereken bir şeyi, 5xx sunucu tarafındaki bir problemi anlatır. Retry mantıkları da genellikle bu ayrıma göre kurulur. 5xx tekrar denenebilir, 4xx genellikle denenmemelidir.

İç detayları sızdırmamak

Stack trace, SQL hata mesajı veya sınıf isimleri hata cevabına girmemeli. Hem güvenlik riski oluşturur hem de client için anlamsızdır.

Bunun yerine bir trace ID döndürmek, destek ekibinin sunucu loglarında ilgili kaydı bulmasını sağlar:

"traceId": "4bf92f3577b34da6"

Hata cevapları bir API’nin en çok okunan ama en az tasarlanan kısmı.

Client geliştiricileri dokümantasyonda başarılı akışı bir kez okur. Hata cevaplarıyla ise her gün uğraşır.