Hata kodları

Bu sayfada, Gemini API ve Firebase AI Logic SDK'ları için yaygın hata kodlarının sorun giderme adımları yer almaktadır.

400 hatası: API key not valid. Please pass a valid API key.

API key not valid. Please pass a valid API key. şeklinde bir 400 hatası alırsanız bu genellikle Firebase yapılandırma dosyanızda/nesnenizde API anahtarının bulunmadığı veya uygulamanız ve/veya Firebase projenizle kullanılacak şekilde ayarlanmadığı anlamına gelir.

Firebase yapılandırma dosyanızda/nesnenizde listelenen API anahtarının uygulamanızın API anahtarıyla eşleştiğinden emin olun. Tüm API anahtarlarınızı Google Cloud konsolundaki API'ler ve Hizmetler > Kimlik Bilgileri panelinde görebilirsiniz.

Eşleşmediklerini fark ederseniz yeni bir Firebase yapılandırma dosyası/nesnesi alın ve uygulamanızdakini değiştirin. Yeni yapılandırma dosyası/nesnesi, uygulamanız ve Firebase projeniz için geçerli bir API anahtarı içermelidir.

400 hatası: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Cloud Storage for Firebase URL'si içeren çok formatlı bir istek göndermeye çalışıyorsanız aşağıdaki 400 hatasıyla karşılaşabilirsiniz:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Bu hata, projede Agent Platform API'si etkinleştirildiğinde gerekli hizmet aracılarının otomatik olarak doğru şekilde sağlanmadığı bir projeden kaynaklanır. Bu, bazı projelerde görülen bilinen bir sorundur ve genel bir düzeltme üzerinde çalışıyoruz.

Projenizi düzeltmek ve bu hizmet aracılarının temel hazırlığını doğru şekilde yapmak için aşağıdaki geçici çözümü uygulayarak çok formatlı isteklerinize Cloud Storage for Firebase URL'lerini eklemeye başlayabilirsiniz. Projenin sahibi olmanız gerekir. Bu görev grubunu projeniz için yalnızca bir kez tamamlamanız yeterlidir.

1. gcloud CLI ile erişim ve kimlik doğrulama.
   Bunu yapmanın en kolay yolu Cloud Shell üzerinden yapmaktır. Google Cloud belgelerinde daha fazla bilgi edinebilirsiniz.

2. İstenirse terminalde gösterilen talimatları uygulayarak gcloud CLI komutunun Firebase projenizde çalıştırılmasını sağlayın.

   Firebase konsolunda Proje ayarları'nın üst kısmında bulabileceğiniz Firebase proje kimliğinize ihtiyacınız olacak.

3. Aşağıdaki komutu çalıştırarak projenizde gerekli hizmet aracılarının temel hazırlığını yapın:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. Hizmet aracılarının temel hazırlığının tamamlanması için birkaç dakika bekleyin ve ardından Cloud Storage for Firebase URL'sini içeren çok formatlı isteğinizi tekrar gönderin.

Birkaç dakika bekledikten sonra bu hatayı almaya devam ederseniz Firebase Destek Ekibi ile iletişime geçin.

403 hatası: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check

To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check şeklinde bir 403 - PERMISSION_DENIED hatası alırsanız isteğinizde geçerli bir App Check jetonu yoktur ve genellikle kötüye kullanılan bir modele erişmeye çalışıyorsunuzdur.

Bazı üretken modellerin, kötü niyetli kişiler tarafından kötüye kullanım için yaygın olarak tercih edildiği tespit edilmiştir.

Firebase AI Logic için App Check zorunlu kılınmadığından projeniz bu modellerin kötüye kullanımına karşı savunmasızdır. Geliştiricilerimizi korumak için Firebase, istek geçerli bir App Check jetonu içermediği sürece bu modellere erişimi engeller (yani Firebase AI Logic için App Check zorunlu kılınır).

Uyarı: 2 Kasım 2026'dan itibaren Firebase AI Logic kullanmak için Firebase App Check yaptırımı zorunlu olacak. Daha fazla bilgi edinin.

Hata döndüren modele erişmek istiyorsanız aşağıdakileri yapın:

1. Firebase AI Logic için App Check hizmetini ayarlayın. Yerel geliştirme için App Check hata ayıklama sağlayıcısını ayarladığınızdan emin olun.

   App Check'i zorunlu kılmak, Gemini API ve Gemini modellerini kötüye kullanıma karşı korumak için çok önemlidir. Bu hatayı gidermek için zorunlu kılınması gerekir.

2. Uygulamanızdan Firebase AI Logic adresine isteği yeniden gönderin.

   Bu istek, geçerli bir App Check jetonu gönderir ve artık bu 403 - PERMISSION_DENIED hatasını almazsınız.

3. Uygulamanızı son kullanıcılara yayınlamadan önce bir üretim onaylama sağlayıcısı oluşturmanız (App Attest, Play Integrity veya reCAPTCHA Enterprise gibi) gerekir. Böylece App Check zorunlu kılındığında son kullanıcılarınız yapay zeka özelliğinize erişebilir.

403 hatası: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check

Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check ifadesini içeren bir 403 - PERMISSION_DENIED hatası alırsanız Firebase projeniz etkin değil olarak tanımlanmıştır ve Firebase AI Logic için App Check zorunlu kılınmamıştır.

"Etkin olmayan projeler", Firebase AI Logic etkinleştirilmiş ancak son zamanlarda Firebase AI Logic kullanımı olmayan projelerdir.

Firebase AI Logic için App Check zorunlu kılınmadığından projeniz Gemini API kötüye kullanımına karşı savunmasız. Projenizi korumak için Firebase, Firebase AI Logic için App Check uygulayana kadar Firebase AI Logic kullanımını devre dışı bıraktı.

Uyarı: 2 Kasım 2026'dan itibaren Firebase AI Logic kullanmak için Firebase App Check yaptırımı zorunlu olacak. Daha fazla bilgi edinin.

Firebase AI Logic uygulamasını tekrar kullanmaya hazır olduğunuzda aşağıdakileri yapın:

1. Firebase AI Logic için App Check hizmetini ayarlayın. Yerel geliştirme için App Check hata ayıklama sağlayıcısını ayarladığınızdan emin olun.

   App Check'i zorunlu kılmak, Gemini API ve Gemini modellerini kötüye kullanıma karşı korumak için çok önemlidir. Bu hatayı gidermek için zorunlu kılınması gerekir.

2. Uygulamanızdan Firebase AI Logic adresine isteği yeniden gönderin.

   Bu istek, geçerli bir App Check jetonu gönderir ve artık bu 403 - PERMISSION_DENIED hatasını almazsınız.

3. App Check politikasını zaten uyguluyor ve bu hatayı almaya devam ediyorsanız Firebase AI Logic için yeniden oynatma korumasının etkin olup olmadığını kontrol edin ("Yalnızca izleme" modu dahil).

   Tekrar oynatma koruması etkin olduğunda Firebase AI Logic için yalnızca sınırlı kullanım jetonları doğrulanmış olarak kabul edilir. Normal oturum jetonları bu hatayı gidermez. Uygulamanızda sınırlı kullanım jetonlarını etkinleştirin veya Firebase AI Logic için tekrar oynatma korumasını devre dışı bırakıp isteği yeniden gönderin ve tekrar oynatma korumasını yeniden etkinleştirmeden önce yaklaşık bir gün bekleyin (proje etkinliği her gün yeniden değerlendirilir).

4. Uygulamanızı son kullanıcılara yayınlamadan önce bir üretim onaylama sağlayıcısı oluşturmanız (App Attest, Play Integrity veya reCAPTCHA Enterprise gibi) gerekir. Böylece App Check zorunlu kılındığında son kullanıcılarınız yapay zeka özelliğinize erişebilir.

403 hatası: PERMISSION_DENIED: The caller does not have permission.

PERMISSION_DENIED: The caller does not have permission. şeklinde bir 403 hatası alırsanız bu genellikle Firebase yapılandırma dosyanızdaki/nesnenizdeki API anahtarının farklı bir Firebase projesine ait olduğu anlamına gelir.

Firebase yapılandırma dosyanızda/nesnenizde listelenen API anahtarının, uygulamanızın API anahtarıyla eşleştiğinden emin olun. Tüm API anahtarlarınızı Google Cloud konsolundaki API'ler ve Hizmetler > Kimlik Bilgileri panelinde görebilirsiniz.

Eşleşmediklerini fark ederseniz yeni bir Firebase yapılandırma dosyası/nesnesi alın ve uygulamanızdakini değiştirin. Yeni yapılandırma dosyası/nesnesi, uygulamanız ve Firebase projeniz için geçerli bir API anahtarı içermelidir.

403 hatası: Requests to this API firebasevertexai.googleapis.com ... are blocked.

Requests to this API firebasevertexai.googleapis.com ... are blocked. şeklinde bir 403 hatası alırsanız bu genellikle uygulamanızdaki Firebase yapılandırmanızda bulunan API anahtarının, gerekli API'yi çağırmasını engelleyen kısıtlamalara sahip olduğu anlamına gelir.

Bu sorunu düzeltmek için Google Cloud konsolunda API anahtarınızın kısıtlamalarını gerekli API'yi içerecek şekilde güncellemeniz gerekir. Firebase AI Logic için Firebase AI Logic API'nin (firebasevertexai.googleapis.com), API anahtarı kullanılarak çağrılabilecek seçili API'ler listesine eklendiğinden emin olmanız gerekir.

Aşağıdaki adımları uygulayın:

1. Google Cloud konsolunda API'ler ve Hizmetler > Kimlik Bilgileri panelini açın.

2. Uygulamanızın kullanmak üzere yapılandırıldığı API anahtarını seçin (örneğin, iOS uygulaması için "iOS anahtarı").

3. API anahtarını düzenle sayfasında API kısıtlamaları bölümünü bulun.

4. Anahtarı kısıtla seçeneğinin belirlendiğinden emin olun. Anahtarınız kısıtlanmamışsa hatanın kaynağı muhtemelen bu değildir.

   Not: Kısıtlanmamış bir API anahtarınız varsa Firebase API anahtarınıza "API kısıtlamaları" uygulamanızı önemle tavsiye ederiz.

5. Selected APIs (Seçili API'ler) açılır menüsünde Firebase AI Logic API'yi arayıp seçerek API anahtarı kullanılarak çağrılabilen seçili API'ler listesine ekleyin.

6. Kaydet'i tıklayın.

   Değişikliklerin geçerlilik kazanması beş dakikayı bulabilir.

Not: Firebase ile ilgili API'ler, API anahtarlarını yalnızca Firebase projesini veya uygulamasını tanımlamak için kullanır, API'yi çağırma yetkisi vermek için kullanmaz (diğer bazı API'lerin izin verdiği gibi). Firebase ile ilgili API'lerin yetkilendirmesi, API anahtarından ayrı olarak Google Cloud IAM izinleri, Firebase Security Rules veya Firebase App Check aracılığıyla yapılır. Firebase API anahtarları hakkında daha fazla bilgi edinin.

404 hatası: Firebase AI Logic genai config not found

Firebase AI Logic genai config not found ifadesini içeren bir 404 hatası alırsanız bu genellikle Firebase AI Logic ayarının yanlış yapılandırıldığı veya eksik olduğu anlamına gelir.

Bu hatanın en olası nedenleri şunlardır:

• Firebase projenizi henüz bir Gemini API sağlayıcı için ayarlamadınız.

  Yapılması gerekenler:
  Firebase konsolunda AI Services (Yapay Zeka Hizmetleri) > AI Logic (Yapay Zeka Mantığı) bölümüne gidin. Başlayın'ı tıklayın ve tercih ettiğiniz Gemini API sağlayıcısını seçin. API'yi etkinleştirdiğinizde Firebase, projenizi ilgili sağlayıcı için yapılandırır. İş akışını tamamladıktan sonra isteğinizi tekrar deneyin.

• Firebase konsolunda Firebase AI Logic kurulum iş akışını çok yakın zamanda tamamladıysanız Firebase AI Logic yapılandırması, geçerli tüm bölgelerdeki gerekli arka uç hizmetlerinin tamamında henüz kullanılamıyor olabilir.

  Yapılması gerekenler:
  Birkaç dakika bekleyip isteğinizi tekrar deneyin.

404 hatası: "was not found or your project does not have access to it" modeli?

Örneğin: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."

Bu tür bir hata almanızın birkaç farklı nedeni olabilir.

• Geçersiz model adı

  • Nedeni: Sağladığınız model adı geçerli bir model adı değil.

  • Düzeltme: Model adınızı ve model sürümünüzü desteklenen ve kullanılabilir tüm modeller listesiyle karşılaştırın. Model adındaki segmentleri ve sıralarını kontrol etmeyi unutmayın. Örneğin:

    • En yeni Gemini 4 Argon model adı: gemini-4-argon
    • En yeni Gemini 3.x Pro model adı: gemini-3.1-pro-preview (yalnızca önizlemede kullanılabilir)
    • En yeni Gemini 3.x Flash model adı: gemini-3.8-flash
    • En yeni Gemini 3.x Flash‑Lite model adı: gemini-3.5-flash-lite
    • En yeni Gemini Nano Banana 2.1 model adı: gemini-nano-banana-2.1
    • En yeni Gemini Nano Banana 2 model adı: gemini-3.1-flash-image
    • En yeni Gemini Nano Banana 2 Lite model adı: gemini-3.1-flash-lite-image
    • En yeni Gemini Nano Banana Pro model adı: gemini-3-pro-image

• Geçersiz konum (yalnızca Agent Platform Gemini API (formerly Vertex AI) sağlayıcısı kullanılıyorsa geçerlidir)

  • Neden: İsteğiniz, modelin kullanılamadığı bir konumdaki modele erişmeye çalışıyor olabilir.

  • Düzeltme: İsteğinizin, modele erişilebilen bir konumdan erişmeye çalıştığından emin olun.

    Agent Platform Gemini API (formerly Vertex AI) kullanırken, başlatma sırasında modele erişmek için isteğe bağlı olarak bir konum belirtebilirsiniz. Bir konum belirtmezseniz Firebase AI Logic varsayılan olarak aşağıdaki konumlara ayarlanır:

    • "Agent Platform" başlatma söz dizimini kullanırken: global
    • Eski "Vertex AI" başlatma söz dizimini kullanırken: us-central1

    Ancak bu varsayılan konumlarda tüm modeller desteklenmez. Bu, modele bağlı olarak başlatma sırasında belirli bir konumu açıkça ayarlamanız gerekebileceği anlamına gelir.

    • Gemini önizleme ve deneysel modeller: Yalnızca global konumunda kullanılabilir.

    • Gemini 4.x ve Gemini 3.x kararlı modelleri: global konumunda ve genellikle us ve eu konumlarında kullanılabilir.

    • Gemini 2.5 modelleri: Birçok konumda kullanılabilir. Gemini Live API 2.5 modellerinin global'da kullanılamadığını unutmayın.

  Modele erişim konumunu belirtme hakkında daha fazla bilgi edinin (kod snippet'leri dahil).

429 hataları: "You exceeded your current quota, please check your plan and billing details" veya "Resource exhausted, please try again later."

Bu tür bir hata almanızın birkaç farklı nedeni olabilir.

• Kotanızı aşıyorsunuz veya eriştiğiniz model diğer kullanıcıların istekleri nedeniyle aşırı yüklendi.

  Yapılacak işlem, Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI) kullanmanıza bağlıdır. Kotalar ve ek kota isteğinde bulunma hakkında daha fazla bilgi için Sıklık sınırları ve kotalar başlıklı makaleyi inceleyin.

  Agent Platform Gemini API (formerly Vertex AI) kullanıyorsanız Google Cloud belgelerinde 429 numaralı hata kodu ile ilgili ek bağlam ve rehberlik sağlanır.

• Faturalandırma gerektiren bir model veya özellik kullanmaya çalışıyorsunuz ancak Firebase projeniz Spark fiyatlandırma planında.

  Gemini Developer API kullanıyorsanız Gemini Developer API "ücretsiz katman"da belirli modellere sınırlı erişim ve birçok temel özelliğe erişim elde edebilirsiniz. Bu katman, ödeme yöntemi belirtmenize gerek kalmadan başlamanıza olanak tanır. Yani Firebase projenizi kullandıkça öde Blaze fiyatlandırma planına yükseltmeniz gerekmez.

  • Bazı modeller Gemini Developer API "ücretsiz katman"da kullanılamaz ve "ücretli katman" gerektirir. Bu durumda projenizin kullandıkça öde Blaze fiyatlandırma planında olması gerekir. Örneğin, aşağıdaki modellerde neredeyse her zaman faturalandırma gerekir:

    • Çoğu önizleme ve deneysel model
    • Medya üreten modeller (Gemini Nano Banana modelleri gibi)

  • Bazı modeller, Gemini Developer API "Ücretsiz Katman"da bazı temel özellikler sunar ancak daha ileri seviye özellikleri kullanmak için "ücretli katman" gerekir. Örneğin:

    • Gemini 3.x modellerinin çoğunu kullanırken Google Search veya Google Maps ile temellendirme için faturalandırma gerekir.

  Firebase fiyatlandırma planları ve Gemini Developer API hakkında bilgi edinin.

  Daha fazla bilgi için Gemini Developer API fiyatlandırma belgelerini ve faturalandırmayla ilgili SSS sayfasını inceleyin.