本页面介绍了 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 控制台的 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 网址。您必须是项目的 Owner,并且只需为项目完成一次这组任务。
使用 gcloud CLI 进行访问和身份验证。
最简单的方法是从 Cloud Shell 执行此操作。如需了解详情,请参阅 Google Cloud 文档。如果出现提示,请按照终端中显示的说明,针对您的 Firebase 项目运行 gcloud CLI。
您需要用到 Firebase 项目 ID,该 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 错误。如需解决此问题,请执行以下某项操作:
在向最终用户发布应用之前,您需要设置生产环境认证提供方(例如 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 错误。如需解决此问题,请执行以下某项操作:
在向最终用户发布应用之前,您需要设置生产环境认证提供方(例如 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 控制台的 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 列表中。
请按照以下步骤操作:
在 Google Cloud 控制台中,打开 API 和服务 > 凭证面板。
选择您的应用配置为使用的 API 密钥(例如,iOS 应用的“iOS 密钥”)。
在修改 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 Logic。点击开始,然后选择您选择的 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 模型时,通过