API hataları

Bu sayfada, GenerateContent API'si tarafından döndürülen arka uç hata kodları için referans sağlanmakta, gRPC hata yanıtı biçimi açıklanmakta ve sorun giderme adımları sunulmaktadır.

HTTP hata kodları

Aşağıdaki tabloda, yaygın olarak görülen arka uç hata kodları, nedenleriyle ilgili açıklamalar ve önerilen çözümler listelenmektedir:

HTTP Kodu Durum Açıklama Örnek Çözüm
400 INVALID_ARGUMENT İstek metni yanlış biçimlendirilmiş. İsteğinizde yazım hatası var veya zorunlu bir alan eksik. İstek biçimi, örnekler ve desteklenen sürümler için API referansına bakın. Daha yeni bir API sürümündeki özellikleri daha eski bir uç nokta ile kullanmak hatalara neden olabilir.
400 FAILED_PRECONDITION Gemini API ücretsiz katmanı ülkenizde kullanılamıyor. Lütfen Google AI Studio'da projenizde faturalandırmayı etkinleştirin. Ücretsiz katmanın desteklenmediği bir bölgede istekte bulunuyorsunuz ve Google AI Studio'da projenizde faturalandırmayı etkinleştirmediniz. Gemini API'yi kullanmak için Google AI Studio'yu kullanarak ücretli bir plan oluşturmanız gerekir.
403 PERMISSION_DENIED API anahtarınız gerekli izinlere sahip değil. Yanlış API anahtarını kullanıyorsunuz. Uygun kimlik doğrulama işleminden geçmeden ayarlanmış bir modeli kullanmaya çalışıyorsunuz. API anahtarınızın ayarlandığından ve doğru erişime sahip olduğundan emin olun. Ayrıca, ince ayarlı modelleri kullanmak için uygun kimlik doğrulama sürecinden geçtiğinizden emin olun.
404 NOT_FOUND İstenen kaynak bulunamadı. İsteğinizde referans verilen bir resim, ses veya video dosyası bulunamadı. İsteğinizdeki tüm parametrelerin API sürümünüz için geçerli olup olmadığını kontrol edin.
429 RESOURCE_EXHAUSTED API'nin hız sınırlarından birini (RPM, TPM, RPD, harcama vb.) aştınız. Çok fazla istek gönderiyor, çok fazla jeton kullanıyor veya hesabınızın fatura geçmişi ve katmanı için harcamaya dayalı sınırları aşıyor olabilirsiniz. Modelin hız sınırları dahilinde olduğunuzu doğrulayın. Bekleyin ve kısa bir süre sonra tekrar deneyin. İsteklerinizin sıklığını veya boyutunu azaltın. Gerekirse hız sınırı artışı isteyin.
499 İPTAL EDİLDİ İşlem iptal edildi (genellikle arayan tarafından). API yanıt vermeyi tamamlamadan önce istemci bağlantıyı kapattı. İstemcinizin veya ağ altyapınızın bağlantıyı erken kapatıp kapatmadığını kontrol edin (ör. istemci tarafında zaman aşımı nedeniyle).
500 ŞİRKET İÇİ Google'dan kaynaklanan beklenmeyen bir hata oluştu. Giriş bağlamınız çok uzun. Devam eden olaylar için Gemini API durum sayfasını kontrol edin. Giriş bağlamınızı azaltın veya geçici olarak başka bir modele (ör. Gemini 2.5 Pro'dan Gemini 2.5 Flash'e) geçip sorunun çözülüp çözülmediğini kontrol edin. Dilerseniz biraz bekleyip isteğinizi yeniden deneyebilirsiniz. Yeniden denedikten sonra sorun devam ederse lütfen Google AI Studio'daki Geri bildirim gönder düğmesini kullanarak sorunu bildirin.
503 UNAVAILABLE Hizmet geçici olarak aşırı yüklü veya kapalı olabilir. Hizmetin kapasitesi geçici olarak dolmuş olabilir. Devam eden olaylar için Gemini API durum sayfasını kontrol edin. Geçici olarak başka bir modele (ör. Gemini 2.5 Pro'dan Gemini 2.5 Flash'e) geçip çalışıp çalışmadığını kontrol edin. Dilerseniz biraz bekleyip isteğinizi yeniden deneyebilirsiniz. Yeniden denedikten sonra sorun devam ederse lütfen Google AI Studio'daki Geri bildirim gönder düğmesini kullanarak sorunu bildirin.
504 DEADLINE_EXCEEDED Hizmet, işleme işlemini son tarihe kadar tamamlayamıyor. İsteminiz (veya bağlamınız), zamanında işlenemeyecek kadar büyük. Bu hatayı önlemek için istemci isteğinizde daha büyük bir "zaman aşımı" ayarlayın.

Hata yanıtı biçimi

Bir GenerateContent isteği başarısız olduğunda API, HTTP durum kodunu (ör. 400 Bad Request, 403 Forbidden veya 429 Too Many Requests) ayarlar ve gRPC durum ayrıntılarını içeren bir JSON yanıt gövdesi döndürür:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Alan Tür Açıklama
code tam sayı HTTP durum kodu.
message dize Hatayla ilgili, kullanıcıların okuyabileceği bir açıklama.
status dize SCREAMING_CASE içindeki gRPC durum kodu.
details dizi ErrorInfo veya LocalizedMessage gibi ek hata bağlamı.

Sırada ne var?