Hata Yanıt Formatı
Tüm hatalar, isteğe bağlı Agent-First ipuçları ile tutarlı bir JSON formatı döner:message, type, code, param) her zaman mevcuttur. İpucu alanları (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) AI ajanının kendi kendine düzeltmesi için isteğe bağlı uzantılardır. Detaylar için Agent-First API guide sayfasına bakın.
OpenAI-uyumlu uç noktalar LemonData’nın stable gateway hata tiplerini kullanır. Anthropic-uyumlu ve Gemini-uyumlu uç noktalar kendi yerel hata ailelerini ve yanıt biçimlerini kullanır.
HTTP Durum Kodları
| Kod | Açıklama |
|---|---|
| 400 | Bad Request - Geçersiz parametreler |
| 401 | Unauthorized - Geçersiz veya eksik API anahtarı |
| 402 | Payment Required - Yetersiz bakiye |
| 403 | Forbidden - Erişim reddedildi veya model izinli değil |
| 404 | Not Found - Model veya kaynak bulunamadı |
| 413 | Payload Too Large - Girdi veya dosya boyutu aşıldı |
| 429 | Too Many Requests - Hız limiti aşıldı |
| 500 | Internal Server Error |
| 502 | Bad Gateway - Üst sağlayıcı hatası |
| 503 | Service Unavailable - Hizmet geçici olarak kullanılamıyor |
| 504 | Gateway Timeout - İstek zaman aşımına uğradı |
Hata Türleri
Kimlik Doğrulama Hataları (401)
| Tür | Kod | Açıklama |
|---|---|---|
invalid_api_key | invalid_api_key | API anahtarı eksik veya geçersiz |
expired_api_key | expired_api_key | API anahtarı iptal edilmiş |
Ödeme Hataları (402)
| Tür | Kod | Açıklama |
|---|---|---|
insufficient_balance | insufficient_balance | Hesap bakiyesi çok düşük (OpenAI-uyumlu uç noktalar) |
insufficient_balance_error | insufficient_balance | Hesap bakiyesi çok düşük (Anthropic-uyumlu uç noktalar) |
quota_exceeded | quota_exceeded | API anahtarı kullanım limiti doldu |
Erişim Hataları (403)
| Tür | Kod | Açıklama |
|---|---|---|
access_denied | access_denied | Kaynağa erişim reddedildi |
access_denied | model_not_allowed | Bu API anahtarı için model izinli değil |
Doğrulama Hataları (400)
| Tür | Açıklama |
|---|---|
invalid_request_error | İstek parametreleri geçersiz |
context_length_exceeded | Girdi model için çok uzun |
model_not_found | İstenen model mevcut genel sözleşmede bulunmuyor |
model_not_found döner.
Hız Limiti Hataları (429)
Hız limitlerini aştığınızda:Retry-After başlığı ve retry_after alanı, yeniden denemeden önce beklenmesi gereken tam saniye sayısını gösterir.
Payload Too Large (413)
Girdi veya dosya boyutu limitleri aştığında:- Görsel dosya çok büyük (maksimum 20MB)
- Ses dosyası çok büyük (maksimum 25MB)
- Girdi metni model bağlam uzunluğunu aşıyor
Üst Sağlayıcı Hataları (502, 503)
| Tür | Açıklama |
|---|---|
upstream_error | Sağlayıcı bir hata döndürdü |
all_channels_failed | Mevcut sağlayıcı yok |
timeout_error | İstek zaman aşımına uğradı |
Python’da Hataları Ele Alma
JavaScript’te Hataları Ele Alma
En İyi Uygulamalar
Üssel geri çekilme (exponential backoff) uygulayın
Üssel geri çekilme (exponential backoff) uygulayın
Hız limitine takıldığınızda, yeniden denemeler arasında giderek daha uzun bekleyin:
Zaman aşımı (timeouts) ayarlayın
Zaman aşımı (timeouts) ayarlayın
Asılı kalan isteklerden kaçınmak için her zaman makul zaman aşımı değerleri ayarlayın:
Hata ayıklama için hataları kayıt altına alın
Hata ayıklama için hataları kayıt altına alın
Destek için istek kimliğini içeren tam hata yanıtını kaydedin:
Modele özgü hataları yönetin
Modele özgü hataları yönetin
Bazı modellerin belirli gereksinimleri vardır (ör. maks token, görüntü formatları).
İstek yapmadan önce girdileri doğrulayın.