错误代码

400 错误：API key not valid. Please pass a valid API key.

如果您收到一条显示 API key not valid. Please pass a valid API key. 的 400 错误，通常意味着 Firebase 配置文件/对象中的 API 密钥不存在，或者未设置为与您的应用和/或 Firebase 项目搭配使用。

检查 Firebase 配置文件/对象中列出的 API 密钥是否与应用的 API 密钥一致。您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中查看所有 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 网址的多模态请求。

如果您在等待几分钟后仍收到此错误，请与 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. 点击保存。

   所做更改最多可能需要 5 分钟才能生效。

403 错误：PERMISSION_DENIED: The caller does not have permission.

如果您收到显示 PERMISSION_DENIED: The caller does not have permission. 的 403 错误，通常意味着 Firebase 配置文件/对象中的 API 密钥属于其他 Firebase 项目。

检查 Firebase 配置文件/对象中列出的 API 密钥是否与应用的 API 密钥一致。您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中查看所有 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 控制台中，依次前往 AI 服务 > AI 逻辑。点击开始，然后选择 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.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 3.x Pro 模型名称：gemini-3.1-pro-preview（仅在预览版中提供）
    • 最新 Gemini 3.x Flash 型号名称： gemini-3.5-flash
    • 最新 Gemini 3.x Flash‑Lite 型号名称： gemini-3.1-flash-lite
    • 最新 Gemini 3.x Pro Image（又称“Nano Banana Pro”）模型名称： gemini-3-pro-image
    • 最新 Gemini 3.x Flash Image（又称“Nano Banana 2”）模型名称： gemini-3.1-flash-image
    • 最新 Gemini 2.5 Flash Image（又称“Nano Banana”）模型名称： gemini-2.5-flash-image

• 位置无效 （仅在使用 Vertex AI Gemini API 提供方时适用）

  • 原因：使用 Vertex AI Gemini API 的每个请求都必须包含用于访问模型的位置信息。您的请求可能尝试访问某个位置中不可用的模型。

  • 解决方法：确保您的请求尝试访问模型时，该模型处于可用状态。

    使用 Vertex AI Gemini API 时，Firebase AI Logic 默认值为 us-central1。不过，并非所有型号都支持 us-central1。这意味着，根据模型，您可能需要在初始化期间明确设置特定位置。

    • Gemini 预览版和实验版模型：必须将位置设置为 global（Live API 模型除外）。所有预览版和实验性 Gemini 模型（Live API 模型除外）仅在 global 位置提供。

    • Gemini 3.x 模型：使用 Firebase AI Logic 时，必须将位置设置为 global。Firebase AI Logic 尚不支持 us 和 eu 位置。

    • Gemini 2.5 模型：您可以选择是否设置位置。如果您未指定位置，则默认值为 us-central1。

    • Gemini Live API 模型：您可以选择是否设置位置。如果您未指定位置，则默认值为 us-central1。请注意，global 位置不受支持。

  详细了解如何指定访问模型的位置（包括代码段）。

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 提供一些额外的背景信息和指导。