API Hata Kodları Referansı

HTTP Durum Kodları

Yaygın API hata durumları
Kod	Durum	Açıklama	Çözüm
400	Bad Request	Beklenen body veya alan tipi yanlış.	JSON gövdesini ve alan adlarını kontrol edin.
401	Unauthorized	Token eksik, geçersiz veya revoke edilmiş.	Bearer token başlığını ve token ömrünü kontrol edin.
402	Payment Required	Premium gerektiren endpoint ücretsiz planda çağrıldı.	Ücretli plan veya uygun capability kullanın.
403	Forbidden	Site scope veya capability kontrolü başarısız oldu.	Doğru site ID ve doğru token ile tekrar deneyin.
404	Not Found	Site bulunamadı veya istenen veri henüz oluşmadı.	Site ID’yi ve ilgili kaynağın üretilmiş olduğunu doğrulayın.
422	Unprocessable Entity	Laravel validation hatası.	Eksik/yanlış alanları validation errors nesnesinden okuyun.
429	Too Many Requests	Throttle limiti aşıldı.	Retry-After kadar bekleyip yeniden deneyin.
500	Server Error	Beklenmeyen sunucu hatası.	İsteği loglayın ve tekrarlıyorsa destek ekibine iletin.

Hata Yanıt Yapısı

API tek bir sabit error envelope kullanmıyor. Auth hataları error alanı döndürür; Laravel validation hataları message ve errors nesnesiyle gelir. errors nesnesi hangi alanın neden geçersiz olduğunu gösterir — hata ayıklamayı hızlandırmak için yanıtın tamamını inceleyin.

{
  "error": "Invalid or revoked token"
}

{
  "message": "The active field is required.",
  "errors": {
    "active": [
      "The active field is required."
    ]
  }
}

429 ve Retry Stratejisi

429 Too Many Requests yanıtıyla birlikte Retry-After başlığı döner. Bu süre dolmadan aynı isteği tekrarlamayın.

İstemcinizde kısa burst’ler için lineer bekleme, tekrarlayan başarısızlıklarda exponential backoff kullanın. Özellikle polling yapan entegrasyonlarda aynı hatalı isteği sık aralıklarla yeniden göndermeyin.