错误代码

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 密钥匹配。您可以在 API 和服务 > 凭据 面板中查看所有 API 密钥。Google Cloud

如果您发现它们不匹配，请 获取新的 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. 如果系统提示，请按照终端中显示的说明操作，使 gcloud CLI 针对您的 Firebase 项目运行。

   您需要 Firebase 项目 ID，您可以在 settings 项目设置 控制台的顶部找到该 ID。Firebase

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。

如需解决此问题，您需要在 API 密钥的限制中更新 Google Cloud 控制台，以包含所需的 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.

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

检查 Firebase 配置文件/对象中列出的 API 密钥是否与应用的 API 密钥匹配。您可以在 API 和服务 > 凭据 面板中查看所有 API 密钥。Google Cloud

如果您发现它们不匹配，请 获取新的 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 Logic。点击开始，然后选择 Gemini Developer API。启用该 API 后，控制台将为 Gemini Developer API 设置 您的项目。完成工作流后，请再次尝试您的请求。

• 如果您最近在 Firebase AI Logic 设置工作流 中完成了 Firebase 控制台，那么您的 Gemini API 密钥可能尚未在所有区域的所有必需后端服务中可用。

  操作方法：
  等待几分钟，然后再次尝试您的请求。

• 您的 Gemini API 密钥可能已从您的 Firebase 项目中删除。

  操作方法：
  了解如何 更改 Gemini API 密钥，供 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-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.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-preview（仅在预览版中提供）
    • 最新 Gemini 3.x Flash Image（又称“Nano Banana 2”）模型名称： gemini-3.1-flash-image-preview（仅在预览版中提供）
    • 最新“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 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 的一些额外背景信息和指南。