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 hal ini berarti
kunci API dalam file/objek konfigurasi Firebase Anda tidak ada atau tidak disiapkan
untuk digunakan dengan aplikasi dan/atau project Firebase Anda.
Pastikan 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 mendapati bahwa kunci tersebut tidak cocok, dapatkan file/objek konfigurasi Firebase yang 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 akan 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 Agent Platform API diaktifkan dalam project. Ini adalah masalah umum pada beberapa project, dan kami sedang berupaya memperbaikinya secara global.
Berikut adalah 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 di project, dan Anda hanya perlu menyelesaikan serangkaian tugas ini sekali untuk project Anda.
Mengakses dan mengautentikasi 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 membuat gcloud CLI berjalan di 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 bahwa agen layanan telah disediakan, lalu coba lagi kirim 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: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Jika Anda menerima error 403 - PERMISSION_DENIED yang menyatakan
To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check,
artinya permintaan Anda tidak memiliki token App Check yang valid dan Anda
mencoba mengakses model yang sering disalahgunakan.
Beberapa model generatif telah diidentifikasi sebagai model yang umum disalahgunakan oleh pihak berniat jahat.
Tanpa App Check, project Anda rentan terhadap penyalahgunaan model ini. Untuk membantu melindungi developer kami, Firebase memblokir akses ke model ini kecuali jika permintaan Anda menyertakan token App Check yang valid (yang mengharuskan App Check diterapkan untuk Firebase AI Logic).
Jika Anda ingin mengakses model yang menampilkan error, lakukan hal berikut:
Siapkan App Check untuk Firebase AI Logic. Untuk pengembangan lokal, pastikan Anda menyiapkan penyedia debug App Check.
Jika Anda sudah menyiapkan App Check, periksa kembali apakah Anda telah menyelesaikan semua langkah dalam petunjuk yang ditautkan.
Kirim ulang permintaan dari aplikasi Anda ke Firebase AI Logic.
Permintaan ini akan mengirimkan token App Check yang valid, dan Anda tidak akan lagi mendapatkan error 403.
Masih mengalami error 403?
Jika App Check diterapkan dan Anda telah mengirim permintaan, tetapi masih mendapatkan error 403, periksa apakah perlindungan replay diterapkan untuk Firebase AI Logic (termasuk dalam mode "Hanya pemantauan").
Saat perlindungan replay diterapkan, hanya token penggunaan terbatas yang dihitung sebagai terverifikasi untuk Firebase AI Logic, yang berarti token sesi reguler tidak dapat menghapus error 403 ini. Untuk memperbaikinya, lakukanlah salah satu langkah berikut:
Opsi 1: Jika Anda ingin menggunakan perlindungan dari replay, periksa kembali penyiapan perlindungan dari replay Anda.
Pastikan Anda telah menyelesaikan semua langkah untuk menyiapkan perlindungan replay, yang mencakup pengaktifan token penggunaan terbatas di codebase aplikasi Anda.
Kirim ulang permintaan ke Firebase AI Logic.
Opsi 2: Jika Anda tidak ingin menggunakan perlindungan replay atau tidak mengaktifkan token penggunaan terbatas di aplikasi, Anda dapat menonaktifkan perlindungan replay.
Batalkan penerapan perlindungan replay di Firebase console: buka tab Security > App Check > APIs, klik untuk meluaskan baris Firebase AI Logic, klik Set up, lalu batalkan penerapan perlindungan replay dalam dialog.
Kirim ulang permintaan ke Firebase AI Logic.
Sebelum merilis aplikasi kepada pengguna akhir, Anda harus menyiapkan penyedia pengesahan produksi (seperti App Attest, Play Integrity, atau reCAPTCHA Enterprise) agar pengguna akhir dapat mengakses fitur AI Anda saat App Check diterapkan.
Error 403: 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
Jika Anda menerima error 403 - PERMISSION_DENIED yang menyatakan
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,
artinya project Firebase Anda telah diidentifikasi sebagai tidak aktif dan permintaan
dari aplikasi Anda tidak memiliki token App Check yang valid.
"Project tidak aktif" adalah project yang mengaktifkan Firebase AI Logic, tetapi tidak memiliki penggunaan Firebase AI Logic baru-baru ini.
Tanpa App Check, project Anda rentan terhadap penyalahgunaan Gemini API. Untuk membantu melindungi project Anda, Firebase menonaktifkan penggunaan Firebase AI Logic hingga permintaan Anda menyertakan token App Check yang valid (yang mengharuskan App Check diterapkan untuk Firebase AI Logic).
Jika Anda sudah siap untuk mulai menggunakan Firebase AI Logic lagi, lakukan hal berikut:
Siapkan App Check untuk Firebase AI Logic. Untuk pengembangan lokal, pastikan Anda menyiapkan penyedia debug App Check.
Jika Anda sudah menyiapkan App Check, periksa kembali apakah Anda telah menyelesaikan semua langkah dalam petunjuk yang ditautkan.
Kirim ulang permintaan dari aplikasi Anda ke Firebase AI Logic.
Permintaan ini akan mengirimkan token App Check yang valid, dan Anda tidak akan lagi mendapatkan error 403.
Masih mengalami error 403?
Jika App Check diterapkan dan Anda telah mengirim permintaan, tetapi masih mendapatkan error 403, periksa apakah perlindungan replay diterapkan untuk Firebase AI Logic (termasuk dalam mode "Hanya pemantauan").
Saat perlindungan replay diterapkan, hanya token penggunaan terbatas yang dihitung sebagai terverifikasi untuk Firebase AI Logic, yang berarti token sesi reguler tidak dapat menghapus error 403 ini. Untuk memperbaikinya, lakukanlah salah satu langkah berikut:
Opsi 1: Jika Anda ingin menggunakan perlindungan dari replay, periksa kembali penyiapan perlindungan dari replay Anda.
Pastikan Anda telah menyelesaikan semua langkah untuk menyiapkan perlindungan replay, yang mencakup pengaktifan token penggunaan terbatas di codebase aplikasi Anda.
Kirim ulang permintaan ke Firebase AI Logic.
Opsi 2: Jika Anda tidak ingin menggunakan perlindungan replay atau tidak mengaktifkan token penggunaan terbatas di aplikasi, Anda dapat menonaktifkan perlindungan replay.
Batalkan penerapan perlindungan replay di Firebase console: buka tab Security > App Check > APIs, klik untuk meluaskan baris Firebase AI Logic, klik Set up, lalu batalkan penerapan perlindungan replay dalam dialog.
Kirim ulang permintaan ke Firebase AI Logic.
Sebelum merilis aplikasi kepada pengguna akhir, Anda harus menyiapkan penyedia pengesahan produksi (seperti App Attest, Play Integrity, atau reCAPTCHA Enterprise) agar pengguna akhir dapat mengakses fitur AI Anda saat App Check diterapkan.
Error 403: PERMISSION_DENIED: The caller does not have permission.
Jika Anda menerima error 403 yang bertuliskan
PERMISSION_DENIED: The caller does not have permission., biasanya ini berarti
kunci API dalam file/objek konfigurasi Firebase Anda adalah milik project Firebase
yang berbeda.
Pastikan 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 mendapati bahwa kunci tersebut tidak cocok, dapatkan file/objek konfigurasi Firebase yang 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 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Jika Anda menerima error 403 yang bertuliskan
Requests to this API firebasevertexai.googleapis.com ... are blocked., biasanya
artinya 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 untuk 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 ini kemungkinan bukan sumber error.
Di menu drop-down Selected APIs, telusuri dan pilih Firebase AI Logic API untuk menambahkannya ke daftar API terpilih yang dapat dipanggil menggunakan kunci API.
Klik Save.
Mungkin perlu waktu hingga lima menit agar perubahan diterapkan.
Error 404: Firebase AI Logic genai config not found
Jika Anda menerima error 404 yang bertuliskan Firebase AI Logic genai config not found,
biasanya berarti setelan untuk Firebase AI Logic salah dikonfigurasi atau
tidak ada.
Berikut adalah kemungkinan penyebab error ini:
Anda belum menyiapkan project Firebase untuk penyedia Gemini API.
Yang harus dilakukan:
Di Firebase console, buka AI Services > AI Logic. Klik Mulai, lalu pilih penyedia Gemini API yang Anda pilih. Aktifkan API, dan Firebase akan menyiapkan project Anda untuk penyedia tersebut. Setelah menyelesaikan alur kerja, coba permintaan Anda lagi.Jika Anda baru saja menyelesaikan alur kerja penyiapan Firebase AI Logic di konsol Firebase, konfigurasi untuk Firebase AI Logic mungkin belum tersedia untuk semua layanan backend yang diperlukan di semua region yang berlaku.
Yang harus dilakukan:
Tunggu beberapa menit, lalu coba lagi permintaan Anda.
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.1-pro-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 mengapa Anda bisa mendapatkan error seperti ini.
Nama model tidak valid
Penyebab: Nama model yang Anda berikan bukan nama model yang valid.
Perbaikan: 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:
- Gemini 4 Hydrogen terbaru
nama model:
gemini-4-hydrogen - Gemini 4 Argon terbaru
nama model:
gemini-4-argon - Gemini 4 Carbon terbaru
nama model:
gemini-4-carbon - Gemini 3.x Flash terbaru
nama model:
gemini-3.8-flash - Gemini 3.x Flash‑Lite terbaru
nama model:
gemini-3.5-flash-lite - Gemini Nano Banana 2.1 terbaru
nama model:
gemini-nano-banana-2.1 - Gemini Nano Banana 2 terbaru
nama model:
gemini-3.1-flash-image - Gemini Nano Banana 2 Lite terbaru
nama model:
gemini-3.1-flash-lite-image - Gemini Nano Banana Pro terbaru
nama model:
gemini-3-pro-image
- Gemini 4 Hydrogen terbaru
nama model:
Model yang dinonaktifkan (dihentikan)
Penyebab: Model yang Anda coba akses telah melewati tanggal penonaktifan (penghentian) dan telah dinonaktifkan secara permanen (misalnya, model Gemini 2.5 penggunaan umum di Agent Platform Gemini API (formerly Vertex AI), model Gemini 2.0, atau model Imagen).
Perbaikan: Periksa FAQ model yang tidak digunakan lagi dan dinonaktifkan, lalu perbarui kode Anda untuk menggunakan model pengganti yang aktif.
Lokasi tidak valid (hanya berlaku jika menggunakan penyedia Agent Platform Gemini API (formerly Vertex AI))
Penyebab: Permintaan Anda mungkin mencoba mengakses model di lokasi tempat model tersebut tidak tersedia.
Perbaikan: Pastikan permintaan Anda mencoba mengakses model di tempat model tersebut tersedia.
Saat menggunakan Agent Platform Gemini API (formerly Vertex AI), Anda dapat menentukan lokasi untuk mengakses model selama inisialisasi secara opsional. Jika Anda tidak menentukan lokasi, Firebase AI Logic akan ditetapkan secara default ke lokasi berikut:
- Saat menggunakan sintaksis inisialisasi "Agent Platform":
global - Saat menggunakan sintaksis inisialisasi "Vertex AI" lama:
us-central1
Namun, tidak semua model didukung di lokasi default ini. Artinya, bergantung pada modelnya, Anda mungkin perlu menetapkan lokasi tertentu secara eksplisit selama inisialisasi.
Model Gemini pratinjau dan eksperimental: Hanya tersedia di lokasi
global.Model stabil Gemini 4.x dan Gemini 3.x: Tersedia di lokasi
globaldan sering kali di lokasiusdaneu.Model Gemini Live API 2.5: Tersedia di banyak lokasi, tetapi tidak tersedia di
global. (Perhatikan bahwa model Gemini 2.5 penggunaan umum telah dinonaktifkan untuk Agent Platform Gemini API (formerly Vertex AI).)
- Saat menggunakan sintaksis inisialisasi "Agent Platform":
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."
Ada beberapa alasan mengapa Anda bisa mendapatkan error seperti ini.
Anda melebihi kuota atau model yang Anda akses kelebihan beban karena permintaan dari orang lain.
Tindakan yang harus diambil bergantung pada apakah Anda menggunakan Gemini Developer API atau Agent Platform Gemini API (formerly Vertex AI). Untuk mengetahui informasi selengkapnya tentang kuota dan cara meminta kuota tambahan, lihat Batas kapasitas dan kuota.
Jika Anda menggunakan Agent Platform Gemini API (formerly Vertex AI), dokumentasi Google Cloud memberikan beberapa konteks dan panduan tambahan untuk Kode error 429.
Anda mencoba menggunakan model atau fitur yang memerlukan penagihan, tetapi project Firebase Anda menggunakan paket harga Spark.
Jika menggunakan Gemini Developer API, Anda bisa mendapatkan akses terbatas ke model tertentu dan akses ke banyak fitur dasar saat menggunakan "paket gratis" Gemini Developer API. Paket ini memungkinkan Anda memulai tanpa harus memberikan metode pembayaran, yang berarti Anda tidak perlu mengupgrade project Firebase ke paket harga Blaze bayar sesuai penggunaan.
Beberapa model tidak tersedia di Gemini Developer API "paket gratis" dan memerlukan "paket berbayar", yang berarti project Anda harus menggunakan paket harga Blaze bayar sesuai penggunaan. Misalnya, model berikut hampir selalu memerlukan penagihan:
- Sebagian besar model pratinjau dan eksperimental
- Model pembuat media (seperti model Gemini Nano Banana)
Beberapa model menawarkan beberapa fitur dasar saat berada di Gemini Developer API "paket gratis", tetapi kemudian memerlukan "paket berbayar" untuk menggunakan fitur lanjutan. Contoh:
- Saat menggunakan sebagian besar model Gemini 3.x,
Grounding dengan
Google Search atauGoogle Maps memerlukan penagihan.
- Saat menggunakan sebagian besar model Gemini 3.x,
Grounding dengan
Pelajari paket harga Firebase dan Gemini Developer API.
Untuk mengetahui detail selengkapnya, lihat Gemini Developer API dokumentasi harga dan FAQ penagihan.