錯誤代碼

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.

如果專案啟用 Vertex AI API 時，沒有正確自動佈建必要的服務代理，就會發生這個錯誤。這是部分專案的已知問題，我們正在設法全面修正。

以下是解決專案問題的替代方案，可正確佈建這些服務代理程式，讓您開始在多模態要求中加入 Cloud Storage for Firebase 網址。您必須是專案的擁有者，且專案只需要完成一次這組工作。

1. 使用 gcloud CLI 存取及驗證。
   最簡單的方法是透過 Cloud Shell 執行這項操作。詳情請參閱Google Cloud說明文件。

2. 如果系統出現提示，請按照終端機顯示的指示，針對 Firebase 專案執行 gcloud CLI。

   您需要 Firebase 專案 ID，這個 ID 位於 Firebase 控制台的「專案設定」settings頂端。

3. 執行下列指令，在專案中佈建必要的服務代理：

   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. 請稍候幾分鐘，確認服務代理程式已佈建完成，然後重試傳送包含 Cloud Storage for Firebase URL 的多模態要求。

如果等待幾分鐘後仍收到這則錯誤訊息，請與 Firebase 支援團隊聯絡。

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 清單。

步驟如下：

1. 在 Google Cloud 控制台中，開啟「API 和服務」>「憑證」面板。

2. 選取應用程式設定使用的 API 金鑰 (例如 iOS 應用程式的「iOS 金鑰」)。

3. 在「編輯 API 金鑰」頁面中，找到「API 限制」部分。

4. 確認已選取「限制金鑰」選項。如果不是，代表金鑰不受限制，這可能不是錯誤來源。

5. 在「選取的 API」下拉式選單中，搜尋並選取要新增的 Firebase AI Logic API，將其加入可使用 API 金鑰呼叫的 API 清單。

6. 按一下 [儲存]。

   變更最多可能需要五分鐘才會生效。

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 金鑰。

404 錯誤：Firebase AI Logic genai config not found

如果您嘗試使用 Gemini Developer API，但收到 404 錯誤訊息 Firebase AI Logic genai config not found，通常表示您的 Firebase 專案沒有可與 Firebase AI Logic 用戶端 SDK 搭配使用的有效 Gemini API 金鑰。

造成這項錯誤最可能的原因如下：

• 您尚未為「Gemini Developer API」設定 Firebase 專案。

  解決方法：
  前往 Firebase 控制台的「Firebase AI Logic」頁面。按一下「開始使用」，然後選取「Gemini Developer API」。啟用 API 後，控制台會為 Gemini Developer API 設定專案。完成工作流程後，請再次提出要求。

• 如果您最近才在 Firebase 控制台中完成 Firebase AI Logic 設定工作流程，則 Gemini API 金鑰可能尚未在所有區域的所有必要後端服務中生效。

  解決方法：
  請稍候片刻，然後再試一次。

• 您的 Gemini API 金鑰可能已從 Firebase 專案中刪除。

  解決方法：
  瞭解如何變更 Firebase AI Logic使用的 Gemini API 金鑰。

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-pro-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version.」

導致這類錯誤的原因有幾種。

• 模型名稱無效

  • 原因：您提供的模型名稱無效。

  • 修正：請根據支援和可用的所有型號清單，檢查型號名稱和型號版本。請務必檢查型號名稱中的區隔及其順序。 例如：

    • Gemini 3.1 Pro 預覽模型名稱為 gemini-3.1-pro-preview。
    • Gemini 3 Flash 預覽模型名稱為 gemini-3-flash-preview。
    • 「Nano Banana Pro」預覽模型名稱為 gemini-3-pro-image-preview。
    • 「Nano Banana 2」預覽模型名稱為 gemini-3.1-flash-image-preview。
    • 「Nano Banana」模型名稱為 gemini-2.5-flash-image。

• 無效位置 (僅適用於使用 Vertex AI Gemini API 供應商和預先發布或實驗性模型)

  • 原因：您使用的是模型的預先發布或實驗版本 (例如 gemini-3.1-pro-preview 和 gemini-3.1-flash-image-preview)，但未指定global位置。

    如果您使用 Vertex AI Gemini API，所有預先發布和實驗 Gemini模型 (Gemini Live 模型除外) 僅適用於 global 地區。不過，由於 Firebase AI Logic 預設為 us-central1 位置，因此使用這些預覽版和實驗版 Gemini 模型時，您需要在程式碼中初始化 Vertex AI Gemini API 後端服務時，明確指定 global 位置。

  • 修正：初始化 Vertex AI Gemini API 服務時，請指定位置 global。進一步瞭解如何指定存取模型的位置 (包括程式碼片段)。

• 位置無效 (僅適用於使用 Vertex AI Gemini API 供應商的情況)

  • 原因：您使用的模型在您嘗試存取的位置不支援。

    如果使用 Vertex AI Gemini API，部分機型僅適用於特定地區。例如 (僅列舉部分內容)：

    • Imagen 模型不支援 global 位置。
    • Gemini Live API 模型 (例如 gemini-2.0-flash-live-preview-04-09) 僅支援 us-central1 位置。
    • Gemini 2.5 模型 (例如 gemini-2.5-pro) 僅適用於global位置、美國境內位置和部分歐洲位置 (如果專案有特殊選項，有時也適用於其他位置)。

  • 修正：初始化 Vertex AI Gemini API 服務時，請務必為使用的模型指定支援的位置。進一步瞭解如何指定存取模型的位置 (包括程式碼片段)，以及模型支援的位置。

    請注意，Firebase AI Logic 預設為 us-central1 位置。

429 錯誤："You exceeded your current quota, please check your plan and billing details" 或 "Resource exhausted, please try again later."

429 錯誤表示您超出配額，或是您存取的模型因其他人的要求而過載。

應採取的行動取決於您使用的是 Gemini Developer API 或 Vertex AI Gemini API。如要進一步瞭解配額和如何申請更多配額，請參閱「速率限制和配額」。

如果您使用 Vertex AI Gemini API，Google Cloud 說明文件會提供錯誤代碼 429 的額外背景資訊和指引。