本頁說明如何排解 Gemini API 和 Firebase AI Logic SDK 的常見錯誤代碼。
400 錯誤:API key not valid. Please pass a valid API key.
如果收到 400 錯誤,並顯示 API key not valid. Please pass a valid API key.,通常表示 Firebase 設定檔/物件中的 API 金鑰不存在,或未設定為與應用程式和/或 Firebase 專案搭配使用。
請確認 Firebase 設定檔/物件中列出的 API 金鑰與應用程式的 API 金鑰 相符。您可以在 Google Cloud 控制台的 「APIs & Services」(API 和服務) >「Credentials」(憑證) 面板中查看所有 API 金鑰。
如果發現不相符,請取得新的 Firebase 設定檔/物件,然後取代應用程式中的設定檔/物件。新的設定檔/物件應包含應用程式和 Firebase 專案的有效 API 金鑰。
400 錯誤:Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
如果嘗試使用 Cloud Storage for Firebase 網址傳送多模態要求,可能會遇到下列 400 錯誤:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
這項錯誤的原因是專案啟用 Agent Platform API 時,未正確自動佈建必要的服務代理。這是部分專案的已知問題,我們正在設法全面修正。
以下是修正專案並正確佈建這些服務代理的解決方法,讓您可以在多模態要求中加入 Cloud Storage for Firebase 網址。您必須是專案的擁有者,且只需為專案完成這組工作一次。
使用 gcloud CLI 存取及驗證。
最簡單的方法是透過 Cloud Shell。詳情請參閱 Google Cloud 說明文件。如果出現提示,請按照終端機中顯示的指示,對 Firebase 專案執行 gcloud CLI。
您需要 Firebase 專案 ID,可在 Firebase 控制台的settings專案設定頂端找到。
執行下列指令,在專案中佈建必要的服務代理:
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 ''
請稍候幾分鐘,確保服務代理已佈建完成,然後重新傳送包含 Cloud Storage for Firebase 網址的多模態要求。
如果等待幾分鐘後仍看到這則錯誤訊息,請與 Firebase 支援團隊聯絡。
403 錯誤:PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
如果收到 403 - PERMISSION_DENIED 錯誤,指出 To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check,表示要求沒有有效的 App Check 權杖,且您嘗試存取經常遭到濫用的模型。
某些生成模型常遭惡意行為人濫用。
如果沒有 App Check,專案就容易遭到濫用。為保護開發人員,Firebase 會封鎖對這些模型的存取,除非要求包含有效的 App Check 權杖 (這需要對 Firebase AI Logic 強制執行 App Check)。
如要存取傳回錯誤的模型,請按照下列步驟操作:
為Firebase AI Logic設定 App Check。 在本機開發時,請務必設定 App Check 偵錯服務。
如果您已設定 App Check,請仔細檢查是否已完成連結操作說明中的所有步驟。
從應用程式重新傳送要求至 Firebase AI Logic。
這項要求會一併傳送有效的 App Check 權杖,您就不會再收到 403 錯誤。
還是收到 403 錯誤嗎?
如果 App Check 已強制執行,且您已傳送要求,但仍收到 403 錯誤,請檢查 Firebase AI Logic 是否強制執行重送保護 (包括「僅限監控」模式)。
強制執行重放攻擊防護機制時,只有有限使用權杖會視為已通過 Firebase AI Logic 驗證,也就是說,一般工作階段符記無法清除這項 403 錯誤。如要解決這個問題,請按照下列其中一種做法進行:
方法 1:如要使用重送防護功能,請仔細檢查重送防護設定。
請確認您已完成設定重放攻擊防護機制的所有步驟,包括在應用程式的程式碼集中啟用有限使用權杖。
重新傳送要求給Firebase AI Logic。
方法 2:如果不想使用重放攻擊防護機制,或應用程式未啟用有限使用權杖,可以停用重放攻擊防護機制。
在 Firebase 控制台中,依序前往 「Security」(安全性) >「App Check」> 「APIs」(API) 分頁, 點選展開「Firebase AI Logic」列,然後點選「Set up」(設定), 在對話方塊中取消強制執行重送防護機制。
重新傳送要求給Firebase AI Logic。
向使用者發布應用程式前,您必須設定正式版認證供應商 (例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise),這樣一來,使用者就能在強制執行 App Check 時存取 AI 功能。
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
如果收到 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,表示 Firebase 專案已判定為閒置,且應用程式的要求不含有效的 App Check 權杖。
「閒置專案」是指已啟用 Firebase AI Logic,但最近沒有任何 Firebase AI Logic 用量的專案。
如果沒有 App Check,專案就容易遭到 Gemini API 濫用。為保護您的專案,Firebase 已停用 Firebase AI Logic,直到您的要求包含有效的 App Check 權杖 (這需要對 Firebase AI Logic 強制執行 App Check)。
準備好再次使用 Firebase AI Logic 時,請按照下列步驟操作:
為Firebase AI Logic設定 App Check。 在本機開發時,請務必設定 App Check 偵錯服務。
如果您已設定 App Check,請仔細檢查是否已完成連結操作說明中的所有步驟。
從應用程式重新傳送要求至 Firebase AI Logic。
這項要求會一併傳送有效的 App Check 權杖,您就不會再收到 403 錯誤。
還是收到 403 錯誤嗎?
如果 App Check 已強制執行,且您已傳送要求,但仍收到 403 錯誤,請檢查 Firebase AI Logic 是否強制執行重送保護 (包括「僅限監控」模式)。
強制執行重放攻擊防護機制時,只有有限使用權杖會視為已通過 Firebase AI Logic 驗證,也就是說,一般工作階段符記無法清除這項 403 錯誤。如要解決這個問題,請按照下列其中一種做法進行:
方法 1:如要使用重送防護功能,請仔細檢查重送防護設定。
請確認您已完成設定重放攻擊防護機制的所有步驟,包括在應用程式的程式碼集中啟用有限使用權杖。
重新傳送要求給Firebase AI Logic。
方法 2:如果不想使用重放攻擊防護機制,或應用程式未啟用有限使用權杖,可以停用重放攻擊防護機制。
在 Firebase 控制台中,依序前往 「Security」(安全性) >「App Check」> 「APIs」(API) 分頁, 點選展開「Firebase AI Logic」列,然後點選「Set up」(設定), 在對話方塊中取消強制執行重送防護機制。
重新傳送要求給Firebase AI Logic。
向使用者發布應用程式前,您必須設定正式版認證供應商 (例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise),這樣一來,使用者就能在強制執行 App Check 時存取 AI 功能。
403 錯誤:PERMISSION_DENIED: The caller does not have permission.
如果收到 403 錯誤,指出 PERMISSION_DENIED: The caller does not have permission.,通常表示 Firebase 設定檔/物件中的 API 金鑰屬於其他 Firebase 專案。
請確認 Firebase 設定檔/物件中列出的 API 金鑰與應用程式的 API 金鑰 相符。您可以在 Google Cloud 控制台的 「APIs & Services」(API 和服務) >「Credentials」(憑證) 面板中查看所有 API 金鑰。
如果發現不相符,請取得新的 Firebase 設定檔/物件,然後取代應用程式中的設定檔/物件。新的設定檔/物件應包含應用程式和 Firebase 專案的有效 API 金鑰。
403 錯誤:Requests to this API firebasevertexai.googleapis.com ... are blocked.
如果收到 403 錯誤,指出 Requests to this API firebasevertexai.googleapis.com ... are blocked.,通常表示應用程式 Firebase 設定中的 API 金鑰設有限制,無法呼叫必要的 API。
如要修正這個問題,請前往 Google Cloud 控制台更新 API 金鑰限制,納入必要的 API。如果是 Firebase AI Logic,您必須確保 Firebase AI Logic API (firebasevertexai.googleapis.com) 包含在所選 API 清單中,可使用 API 金鑰呼叫。
步驟如下:
在 Google Cloud 控制台中,依序開啟「APIs & Services」(API 和服務) >「Credentials」(憑證) 面板。
選取應用程式設定使用的 API 金鑰 (例如 iOS 應用程式的「iOS 金鑰」)。
在「編輯 API 金鑰」頁面,找到「API 限制」部分。
確認已選取「限制金鑰」選項。如果沒有,表示金鑰未受限制,這可能不是錯誤來源。
在「Selected APIs」(已選取的 API) 下拉式選單中,搜尋並選取「 Firebase AI Logic API」,將其新增至 可使用 API 金鑰呼叫的 API 清單。
按一下「儲存」。
變更最多可能需要五分鐘才會生效。
404 錯誤:Firebase AI Logic genai config not found
如果收到 404 錯誤,指出 Firebase AI Logic genai config not found,通常表示 Firebase AI Logic 的設定有誤或遺漏。
以下是造成這項錯誤最可能的原因:
您尚未為 Gemini API 供應商設定 Firebase 專案。
操作步驟:
在 Firebase 控制台,依序前往「AI Services」(AI 服務) > 「AI Logic」。按一下「Get started」(開始使用),然後選取您選擇的 Gemini API 供應商。啟用 API 後,Firebase 就會為該供應商設定專案。完成工作流程後,請再次嘗試要求。如果您最近才在 Firebase 控制台中完成 Firebase AI Logic 設定工作流程,則 Firebase AI Logic 設定可能尚未套用至所有適用區域中的所有必要後端服務。
處理方式:
請稍候幾分鐘,然後再試一次。
404 錯誤:模型「was not found or your project does not have access to it」?
例如:「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.」
這類錯誤可能由多種原因造成。
模型名稱無效
原因:您提供的模型名稱無效。
修正方式:請根據所有支援和可用模型的清單,檢查模型名稱和模型版本。請務必檢查模型名稱中的區隔和順序。例如:
- 最新 Gemini 4 Hydrogen
模型名稱:
gemini-4-hydrogen - 最新 Gemini 4 Argon
模型名稱:
gemini-4-argon - 最新 Gemini 4 Carbon
模型名稱:
gemini-4-carbon - 最新 Gemini 3.x Flash
模型名稱:
gemini-3.8-flash - 最新 Gemini 3.x Flash‑Lite
模型名稱:
gemini-3.5-flash-lite - 最新 Gemini Nano Banana 2.1
模型名稱:
gemini-nano-banana-2.1 - 最新 Gemini Nano Banana 2
模型名稱:
gemini-3.1-flash-image - 最新 Gemini Nano Banana 2 Lite
模型名稱:
gemini-3.1-flash-lite-image - 最新 Gemini Nano Banana Pro
模型名稱:
gemini-3-pro-image
- 最新 Gemini 4 Hydrogen
模型名稱:
停用 (淘汰) 模型
原因:您嘗試存取的模型已超過停用 (淘汰) 日期,並已永久停用 (例如 Agent Platform Gemini API (formerly Vertex AI) 的一般用途 Gemini 2.5 模型、Gemini 2.0 模型或 Imagen 模型)。
修正方式:請參閱淘汰和停用模型的常見問題,並更新程式碼,改用有效的替代模型。
位置無效 (僅適用於使用 Agent Platform Gemini API (formerly Vertex AI) 供應商的情況)
原因:要求可能嘗試存取不支援該模型的位置。
修正方式:確認要求存取的模型位於可用位置。
使用 Agent Platform Gemini API (formerly Vertex AI) 時,您可以選擇指定位置,以便在初始化期間存取模型。如未指定位置,Firebase AI Logic 會預設為下列位置:
- 使用「Agent Platform」初始化語法時:
global - 使用舊版「Vertex AI」初始化語法時:
us-central1
不過,這些預設位置不支援所有模型。這表示視模型而定,您可能需要在初始化期間明確設定特定位置。
Gemini 預先發布版和實驗模型:僅適用於
global位置。Gemini 4.x 和 Gemini 3.x 穩定版模型:可在
global位置使用,通常也可在us和eu位置使用。Gemini Live API 2.5 模型: 在許多地區推出,但不適用於
global。(請注意,一般用途的 Gemini 2.5 模型已在 Agent Platform Gemini API (formerly Vertex AI)停用)。
- 使用「Agent Platform」初始化語法時:
進一步瞭解如何指定存取模型的地點 (包括程式碼片段)。
429 錯誤:"You exceeded your current quota, please check your plan and billing details" 或 "Resource exhausted, please try again later."
這類錯誤可能由多種原因造成。
您已超過配額,或您存取的模型因其他人的要求而超載。
應採取的行動取決於您使用的是 Gemini Developer API 還是 Agent Platform Gemini API (formerly Vertex AI)。如要進一步瞭解配額和如何申請更多配額,請參閱「頻率限制和配額」。
如果您使用的是 Agent Platform Gemini API (formerly Vertex AI),Google Cloud 說明文件會提供錯誤代碼 429 的其他背景資訊和指南。
您嘗試使用的模型或功能需要計費,但 Firebase 專案採用 Spark 定價方案。
如果使用 Gemini Developer API,可以有限度地存取特定模型,並在 Gemini Developer API「免費方案」中使用許多基本功能。這個級別不需提供付款方式即可開始使用,也就是說,您不必將 Firebase 專案升級至即付即用 Blaze 定價方案。
部分模型不適用於 Gemini Developer API「免費方案」,必須使用「付費方案」,也就是說,專案必須採用即付即用 Blaze 定價方案。舉例來說,下列模型幾乎一律需要計費:
- 大多數預先發布版和實驗模型
- 媒體生成模型 (例如 Gemini Nano Banana 模型)
有些模型在Gemini Developer API「免費方案」中提供一些基本功能,但需要「付費方案」才能使用更進階的功能。例如:
- 使用大多數 Gemini 3.x 模型時,透過
Google Search 或Google Maps 建立基準需付費。
- 使用大多數 Gemini 3.x 模型時,透過