Starting November 2, 2026, Firebase App Check enforcement will be required to use Firebase AI Logic. Learn more.
Model updates:
The latest Gemini models, like Gemini 3.8 Flash, are available to use with
Firebase AI Logic! Learn more.
Gemini 2.5 models will shut down in October 2026 (and new projects cannot start
using them). To avoid service disruptions, update to a newer model (like
gemini-3.8-flash or
gemini-3.1-flash-image).
Any stable Gemini Live API 2.5 models are not impacted.
Learn more.
本页介绍了如何排查 Gemini API 和 Firebase AI Logic SDK 的常见错误代码。
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.
此错误是由以下原因造成的：在项目中启用 Agent Platform API 时，未正确自动预配所需的服务代理。这是某些项目的已知问题，我们正在努力寻找全局修复方案。
以下是解决项目问题并正确配置这些服务代理的解决方法，以便您开始在多模态请求中添加 Cloud Storage for Firebase 网址。您必须是项目的所有者，并且只需为项目完成一次这组任务。
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 项目已被识别为处于闲置状态，并且您未针对 Firebase AI Logic 强制执行 App Check。
“非活跃项目”是指已启用 Firebase AI Logic 但最近未使用过 Firebase AI Logic 的项目。
由于您未针对 Firebase AI Logic 强制执行 App Check，因此您的项目容易受到 Gemini API 的滥用。为了帮助保护您的项目，Firebase 已停用 Firebase AI Logic 的使用，直到您为 Firebase AI Logic 强制执行 App Check。
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 密钥。
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 列表中。
在所选 API 下拉菜单中，搜索并选择 Firebase AI Logic API，以将其添加到可以使用该 API 密钥调用的所选 API 的列表中。
点击保存。
所做更改最多可能需要 5 分钟才能生效。
404 错误：Firebase AI Logic genai config not found
如果您收到内容为 Firebase AI Logic genai config not found 的 404 错误，通常意味着 Firebase AI Logic 的设置配置有误或缺失。
以下是此错误的最可能原因：
您尚未为 Gemini API 提供商设置 Firebase 项目。
操作步骤：
在 Firebase 控制台中，依次前往 AI 服务 > AI 逻辑。点击开始，然后选择您选择的 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.”
