Hata Kodları

Bir şeyler ters gittiğinde API rastgele bir mesaj dönmez. Her hata hep aynı düzende, makinelerin ve insanların birlikte okuyabildiği tek bir standart biçimde gelir. Sistemde toplam 50 farklı iş hatası tanımlıdır. Aynı hata her zaman aynı kod ve aynı HTTP durumuyla döner — yani bir kez tanıdığınız hatayı her yerde tanırsınız.

Hata biçimi: RFC 7807 ProblemDetails

Tüm hatalar RFC 7807 ProblemDetails (hataların standart JSON biçimi) formatında döner. Bu format sayesinde ister bir uygulama ister bir insan, hatanın ne olduğunu ve nasıl çözüleceğini aynı alanlara bakarak anlar. Alanların anlamı şöyle:

Hata yanıtı neye benzer?

Aşağıda gerçek bir hata yanıtı var. Kayıt sırasında kullanıcı anahtarı çok kısa, müşteri numarası da boş gönderilmişse API şuna benzer bir JSON döner:

{
  "type": "https://yos.91.98.230.19.nip.io/errors/error.validation.failed",
  "title": "Doğrulama hatası",
  "detail": "Bir veya daha fazla alan geçersiz. Lütfen girdilerinizi kontrol edin.",
  "status": 400,
  "instance": "/api/v1/auth/register",
  "code": "error.validation.failed",
  "traceId": "0HN7G8K5H2J3L4M5",
  "errors": {
    "userKey": ["UserKey en az 3 karakter olmalı"],
    "customerNo": ["CustomerNo boş olamaz"]
  }
}

Buradaki errors alanı yalnızca form doğrulama hatalarında görünür — her alanın yanında sorunun ne olduğu yazar, böylece kullanıcıya tam olarak hangi kutuyu düzelteceğini gösterebilirsiniz. Diğer hatalarda bu alan bulunmaz.

Dil nasıl seçilir? Önce isteğin Accept-Language başlığına bakılır; o yoksa kullanıcının hesabındaki tercih edilen dile; o da yoksa varsayılan olarak Türkçeye düşülür. Yani title ve detail metinleri kullanıcının diline göre gelirken code her zaman İngilizce ve sabit kalır.

Bir hatayı adım adım nasıl çözerim?

Kısa yol: koda bakın, sorunu anlayın; çözemezseniz traceId ile logdan detayına inin.

• 1. code'a bakın. Örneğin 404 error.account.not_found = istenen hesap bulunamadı. Kod size hatanın tam sebebini söyler; aşağıdaki tablolarda her kodun ne anlama geldiğini bulabilirsiniz.
• 2. detail'i okuyun. Çoğu hata ne yapılması gerektiğini de söyler (örn. "Lütfen bağlantı akışını yeniden başlatın").
• 3. Hâlâ anlaşılmıyorsa traceId'yi kopyalayın ve Kibana'da aratın. Bu takip numarası o isteğe ait tüm log satırlarını (isteğin gövdesi, hata, varsa bankaya/kuruma giden çağrı) tek yerde toplar.

HTTP durum kodları ne anlama gelir?

HTTP durumu hatanın kaba türünü söyler. Kabaca: 4xx = "isteğinizde bir sorun var, düzeltip tekrar deneyin"; 5xx = "sunucu/banka/kurum tarafında bir sorun var, genelde bekleyip tekrar denemek gerekir".

Tüm hata kodları

Hatalar konularına göre gruplanmıştır. Her satırda soldan sağa: HTTP durumu, makine kodu, kullanıcıya gösterilen başlık ve açıklama yer alır.