Halaman ini memberikan pemecahan masalah kode error umum untuk SDK Gemini API dan Firebase AI Logic.
Error 400: API key not valid. Please pass a valid API key.
Jika Anda menerima error 400 yang menyatakan
API key not valid. Please pass a valid API key., biasanya berarti kunci API di file/objek konfigurasi Firebase Anda tidak ada atau tidak disiapkan
untuk digunakan dengan aplikasi dan/atau project Firebase Anda.
Periksa apakah kunci API yang tercantum dalam file/objek konfigurasi Firebase Anda cocok dengan kunci API untuk aplikasi Anda. Anda dapat melihat semua kunci API di panel APIs & Services > Credentials di Google Cloud console.
Jika Anda menemukan bahwa keduanya tidak cocok, dapatkan file/objek konfigurasi Firebase baru, lalu ganti file/objek yang ada di aplikasi Anda. File/objek konfigurasi baru harus berisi kunci API yang valid untuk aplikasi dan project Firebase Anda.
Error 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Jika Anda mencoba mengirim permintaan multimodal dengan URL Cloud Storage for Firebase, Anda mungkin mengalami error 400 berikut:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Error ini disebabkan oleh project yang tidak memiliki agen layanan yang diperlukan yang disediakan secara otomatis dengan benar saat Vertex AI API diaktifkan di project. Ini adalah masalah umum pada beberapa project, dan kami sedang berupaya melakukan perbaikan global.
Berikut solusi untuk memperbaiki project Anda dan menyediakan agen layanan ini dengan benar sehingga Anda dapat mulai menyertakan URL Cloud Storage for Firebase dalam permintaan multimodal Anda. Anda harus menjadi Pemilik project, dan Anda hanya perlu menyelesaikan serangkaian tugas ini satu kali untuk project Anda.
Akses dan autentikasi dengan gcloud CLI.
Cara termudah untuk melakukannya adalah dari Cloud Shell. Pelajari lebih lanjut di dokumentasi Google Cloud.Jika diminta, ikuti petunjuk yang ditampilkan di terminal untuk menjalankan gcloud CLI terhadap project Firebase Anda.
Anda memerlukan project ID Firebase, yang dapat ditemukan di bagian atas settings Project settings di Firebase console.
Sediakan agen layanan yang diperlukan di project Anda dengan menjalankan perintah berikut:
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 ''
Tunggu beberapa menit untuk memastikan agen layanan disediakan, lalu coba lagi mengirim permintaan multimodal Anda yang menyertakan URL Cloud Storage for Firebase.
Jika Anda masih mendapatkan error ini setelah menunggu beberapa menit, hubungi Dukungan Firebase.
Error 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Jika Anda menerima error 403 yang menyatakan
Requests to this API firebasevertexai.googleapis.com ... are blocked., biasanya
berarti kunci API dalam konfigurasi Firebase di aplikasi Anda memiliki
pembatasan yang mencegahnya memanggil API yang diperlukan.
Untuk memperbaikinya, Anda perlu memperbarui batasan kunci API di konsol Google Cloud agar menyertakan API yang diperlukan. Untuk Firebase AI Logic,
Anda harus memastikan Firebase AI Logic API
(firebasevertexai.googleapis.com) disertakan dalam daftar API yang dipilih
yang dapat dipanggil menggunakan kunci API.
Ikuti langkah-langkah berikut:
Di Google Cloud console, buka panel APIs & Services > Credentials.
Pilih kunci API yang dikonfigurasi untuk digunakan oleh aplikasi Anda (misalnya, "kunci iOS" untuk aplikasi iOS).
Di halaman Edit API key, temukan bagian API restrictions.
Pastikan opsi Restrict key dipilih. Jika tidak, kunci Anda tidak dibatasi, dan kemungkinan ini bukan sumber error.
Di menu drop-down Selected APIs, telusuri dan pilih Firebase AI Logic API untuk menambahkannya ke daftar API yang dipilih yang dapat dipanggil menggunakan kunci API.
Klik Save.
Mungkin diperlukan waktu hingga lima menit agar perubahan diterapkan.
Error 403: PERMISSION_DENIED: The caller does not have permission.
Jika Anda menerima error 403 yang menyatakan
PERMISSION_DENIED: The caller does not have permission., biasanya berarti kunci API dalam file/objek konfigurasi Firebase Anda termasuk dalam project Firebase yang berbeda.
Periksa apakah kunci API yang tercantum dalam file/objek konfigurasi Firebase Anda cocok dengan kunci API untuk aplikasi Anda. Anda dapat melihat semua kunci API di panel APIs & Services > Credentials di Google Cloud console.
Jika Anda menemukan bahwa keduanya tidak cocok, dapatkan file/objek konfigurasi Firebase baru, lalu ganti file/objek yang ada di aplikasi Anda. File/objek konfigurasi baru harus berisi kunci API yang valid untuk aplikasi dan project Firebase Anda.
Error 404: Firebase AI Logic genai config not found
Jika Anda mencoba menggunakan Gemini Developer API dan menerima error 404 yang menyatakan Firebase AI Logic genai config not found, biasanya berarti project Firebase Anda tidak memiliki kunci API Gemini yang valid untuk digunakan dengan SDK klien Firebase AI Logic.
Berikut adalah kemungkinan penyebab error ini:
Anda belum menyiapkan project Firebase untuk Gemini Developer API.
Yang harus dilakukan:
Di konsol Firebase, buka Layanan AI > AI Logic. Klik Mulai, lalu pilih Gemini Developer API. Aktifkan API, dan konsol akan menyiapkan project Anda untuk Gemini Developer API. Setelah menyelesaikan alur kerja, coba lagi permintaan Anda.Jika Anda baru saja menyelesaikan alur kerja penyiapan Firebase AI Logic di konsol Firebase, kunci API Gemini Anda mungkin belum tersedia untuk semua layanan backend yang diperlukan di semua region.
Yang harus dilakukan:
Tunggu beberapa menit, lalu coba permintaan Anda lagi.Kunci API Gemini Anda mungkin telah dihapus dari project Firebase Anda.
Yang harus dilakukan:
Pelajari cara mengubah kunci API Gemini yang digunakan oleh Firebase AI Logic.
Error 404: model "was not found or your project does not have access to it"?
Misalnya: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3-pro-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."
Ada beberapa alasan berbeda mengapa Anda bisa mendapatkan error seperti ini.
Nama model tidak valid
Penyebab: Nama model yang Anda berikan bukan nama model yang valid.
Perbaiki: Periksa nama model dan versi model Anda berdasarkan daftar semua model yang didukung dan tersedia. Pastikan untuk memeriksa segmen dan urutannya dalam nama model. Contoh:
- Nama model Gemini 3.x Pro terbaru:
gemini-3.1-pro-preview(hanya tersedia dalam pratinjau) - Nama model Gemini 3.x Flash terbaru:
gemini-3.5-flash - Nama model Gemini 3.x Flash‑Lite terbaru:
gemini-3.1-flash-lite - Nama model Gemini 3.x Pro Image terbaru (alias "Nano Banana Pro"):
gemini-3-pro-image-preview(hanya tersedia dalam pratinjau) - Nama model Gemini 3.x Flash Image terbaru (alias "Nano Banana 2"):
gemini-3.1-flash-image-preview(hanya tersedia dalam pratinjau) - Nama model "Nano Banana" terbaru:
gemini-2.5-flash-image
- Nama model Gemini 3.x Pro terbaru:
Lokasi tidak valid (hanya berlaku jika menggunakan penyedia Vertex AI Gemini API)
Penyebab: Setiap permintaan Anda yang menggunakan Vertex AI Gemini API harus menyertakan lokasi untuk mengakses model. Permintaan Anda mungkin mencoba mengakses model di lokasi yang tidak menyediakan model tersebut.
Solusi: Pastikan permintaan Anda mencoba mengakses model yang tersedia.
Saat menggunakan Vertex AI Gemini API, Firebase AI Logic secara default adalah
us-central1. Namun, tidak semua model didukung dius-central1. Artinya, bergantung pada modelnya, Anda mungkin perlu menetapkan lokasi tertentu secara eksplisit selama inisialisasi.Pratinjau Gemini dan model eksperimental: Setelan lokasi ke
globaldiperlukan (kecuali untuk model Live API). Semua model Gemini pratinjau dan eksperimental (kecuali model Live API) hanya tersedia di lokasiglobal.Model Gemini 3.x: Menetapkan lokasi ke
globaldiperlukan saat menggunakan Firebase AI Logic. Firebase AI Logic belum mendukung lokasiusdaneu.Model Gemini 2.5: Menetapkan lokasi bersifat opsional. Jika Anda tidak menentukan lokasi, defaultnya adalah
us-central1.Model Gemini Live API: Menetapkan lokasi bersifat opsional. Jika Anda tidak menentukan lokasi, defaultnya adalah
us-central1. Perhatikan bahwa lokasiglobaltidak didukung.
Pelajari lebih lanjut cara menentukan lokasi untuk mengakses model (termasuk cuplikan kode).
Error 429: "You exceeded your current quota, please check your plan and billing details" atau "Resource exhausted, please try again later."
Error 429 menunjukkan bahwa Anda melebihi kuota atau model yang Anda akses kelebihan beban karena permintaan dari orang lain.
Tindakan yang harus dilakukan bergantung pada apakah Anda menggunakan Gemini Developer API atau Vertex AI Gemini API. Untuk mengetahui informasi selengkapnya tentang kuota dan cara meminta kuota tambahan, lihat Batas frekuensi dan kuota.
Jika Anda menggunakan Vertex AI Gemini API, dokumentasi Google Cloud memberikan beberapa konteks dan panduan tambahan untuk Kode error 429.