Hata Kodları V1

API hata yanıtlarını HTTP durum kodları ve dönen hata açıklamaları üzerinden değerlendirin. Bu sayfa mevcut hata davranışlarını, hata yönetimi önerilerini ve planlanan ortak hata kodu standardını ele alır.

HTTP Durum Kodları

HTTP durumları ve önerilen işlemler

Bulbulustur API, HTTP durum kodlarıyla isteğin sonucunu bildirir. Yanıt gövdesindeki success ve errorType işleme ilişkin ek bilgi sağlar.

Durum	Anlam	Entegrasyon davranışı
`200`	Başarılı	Yanıttaki `data` alanını işle
`400`	Geçersiz istek veya iş kuralı	Parametreyi/iş koşulunu düzelt; körlemesine yeniden deneme
`401`	Kimlik doğrulama başarısız	API Key ve API Secret değerlerini kontrol et
`403`	Yasak	Yetki veya erişim politikasını kontrol et; her endpointin bu kodu ürettiği garanti değildir
`404`	Kaynak bulunamadı	Gönderilen varyant/sipariş/iade kimliğini doğrula
`429`	İstek limiti aşıldı	İstek hızını azalt ve artan gecikmeyle tekrar dene
`500`	Beklenmedik sunucu hatası	İstek bağlamını kaydet, güvenli tekrar deneme stratejisi uygula
`502`	Bağımlı servis hatası	Referans servisi geçici olarak kullanılamıyor olabilir; kontrollü tekrar dene

Not: Bu tablo HTTP anlamlarını ve mevcut implementasyonlarda görülen durumları açıklar; bütün endpointlerin bütün durum kodlarını üretmesi beklenmez.

HTTP · ÖrnekKaynak bulunamadı

HTTP/1.1 404 Not Found
Content-Type: application/json

Hata Yanıtı Modeli

Result ve hata alanları

Bulbulustur'un mevcut servis yanıtları Result veya Result<T> yapısını kullanır. Hata yanıtları tek bir error nesnesi içine sarılmak zorunda değildir.

Result hata alanları

successboolean

İşlemin başarılı olup olmadığını bildirir; Result.AsError(...) için false.

messagestring

İnsan tarafından okunabilen hata açıklaması. Sabit bir makine kodu gibi ayrıştırmayın.

errorTypeenum

İç ErrorType türü: None (0), BussinessRuleViolation (1), Exception (2). Varsayılan JSON enum yapılandırmasına göre sayı olarak serileştirilebilir; özel sabit JSON enum string sözleşmesi ilan edilmemiştir.

responseId, responseKeyinteger, string

Sonuç nesnesinin ek alanlarıdır; her hata için dolu ve benzersiz hata izleme kimliği oldukları garanti edilmez.

Modelde ayrıca exception ve messageReplacements alanları bulunur. Public API'de bunlara güvenerek iş akışı kurmayın. İstisna ayrıntılarının dışarı dönmemesi ayrıca güvenlik incelemesinde ele alınmalıdır.

JSON · 404Şematik Result örneği

{
  "success": false,
  "message": "Ürün Bulunamadı!",
  "errorType": 1,
  "responseId": 0,
  "responseKey": null
}

Örnek, ProductController'daki bulunamayan varyant davranışını temel alır; tüm serileştirilmiş Result alanlarını göstermez.

Hata Türleri ve Örnekler

Doğrulanmış durum senaryoları

Hata türünü tek başına HTTP statüsünün yerine kullanmayın. Aynı BussinessRuleViolation türü farklı controllerlarda 400, 401 veya 404 ile dönebilir.

Doğrulanmış örnekler

İstek	Durum	Neden
`GET /api/products/{variantId}`	`404`	Belirtilen ürün varyantı bulunamadı
`GET /api/categories?languageId=99`	`400`	Geçersiz dil aralığı
`GET /api/brands`	`401`	Geçerli mağaza kimliği bulunamadı
`GET /api/colors`	`502`	Referans veri servisi erişilemiyor
Rate-limit politikalı istek	`429`	Bir dakikalık istek kotası aşıldı

Parametre hatalarını düzeltmek gerekir; geçici bağımlılık sorunlarında yeniden deneme uygun olabilir.

cURLBulunamayan varyant örneği

curl --request GET \
  'https://developers.bulbulustur.com/api/products/999999999' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Api-Secret: YOUR_API_SECRET'

Kimlik temsilidir; 404 döneceği gerçek ortamda garanti edilmez.

Hata Yönetimi

İstemci entegrasyonu ve yeniden deneme

HTTP koduna göre karar

400 ve 404: Parametre veya kaynak kimliğini düzeltin. Aynı isteği değiştirmeden tekrar etmek genellikle çözüm değildir.

401: Anahtar/secret ve bağlı mağaza durumunu kontrol edin. Hatalı kimlik bilgileriyle sürekli tekrar denemeyin.

429: İstek hızını azaltın. Sunucu Retry-After sağlıyorsa esas alın; her yanıtta garanti değildir. Aksi durumda artan gecikme ve jitter uygulayın.

500 / 502 / 503 / 504: Geçici hata olabilir. Salt okunur GET istekleri, sınırlı sayıda tekrar denenebilir; veri değiştiren işlemleri idempotency güvencesi doğrulanmadan otomatik tekrarlamayın.

Loglama

İstek yolu, HTTP statüsü, UTC zaman, endpoint ve gizli olmayan korelasyon bilgilerini kaydedin. API Key / API Secret veya kişisel verileri loglamayın.

İstek hızı

Mevcut fixed politikası genel API'de dakika başına 120, kimlik testi yolunda dakika başına 20 istek / istemci IP sınırı uygular. Limitler bölümüne bakın.

Örnek akışHTTP hata yönetimi

GET request
  2xx  → response data işle
  400  → parametreyi düzelt
  401  → kimlik bilgilerini kontrol et
  404  → kaynak kimliğini doğrula
  429  → backoff + jitter
  5xx  → sınırlı retry (GET için)