Gemini 3.5 Flash 报 403 怎么办?密钥没错为什么还是 PERMISSION_DENIED?
11 月 5 日上午,我把一个旧项目切到 gemini-3.5-flash。环境变量明明能读到 Key,请求却直接返回 403。
结论先放这:PERMISSION_DENIED 不等于“密钥填错”。排查时看四条路径:模型与接口是否可用、凭据作用域、来源限制、账户权限。最快的分界方法,是绕开业务代码发一个最小请求。最小请求成功而业务代码失败,就查本地配置;最小请求也返回 403,就查服务端权限。
下面的权限名、模型 ID 和判断逻辑,均按 2026 年 11 月 5 日 Google 官方文档及实时模型目录核对。gemini-3.5-flash 的价格、上下文窗口和支持区域没有拿其他 Flash 型号的数据硬套,具体开放范围仍以你的项目实时返回为准。
为什么密钥没问题,仍然会报 403?
403 表示请求已经到达服务,但当前调用身份没有访问目标资源的权限。它和 401 不一样:401 更偏向凭据缺失或无效,403 经常是“服务认识你,但不让你进”。
我当时看到的完整响应就是这种结构:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error":{"code":403,"message":"Permission denied.","status":"PERMISSION_DENIED"}}
说实话,一开始我也盯着 Key 折腾了半天。删掉重建、重新复制、检查换行,全是无效操作。真正的问题是调用渠道和凭据类型混用了。
先按现象对号入座:
| 你的现象 | 优先检查 | 原因 |
|---|---|---|
| 模型列表查询也返回 403 | API Key 限制、接口启用状态 | 请求还没走到具体模型 |
| 模型列表查询成功,生成请求 403 | 模型开放范围、目标模型权限 | Key 可用,但目标资源不可访问 |
| 最小请求成功,业务请求 403 | Base URL、环境变量、代理层、旧凭据 | 服务端权限基本正常 |
| Vertex AI 请求 403 | ADC 身份、IAM、项目和区域 | Vertex AI 不使用普通 API Key 鉴权 |
| 本机成功,服务器失败 | IP、HTTP Referrer、应用限制 | 请求来源发生了变化 |
排查顺序别反。否则很容易在 IAM 页面里点半天,最后发现模型 ID 压根不在当前渠道的可见列表里。
flowchart TD
A[收到 403 PERMISSION_DENIED] --> B{模型列表查询是否成功}
B -- 否 --> C[检查接口启用状态与 Key 限制]
B -- 是 --> D{最小生成请求是否成功}
D -- 是 --> E[检查本地 SDK、端点与环境变量]
D -- 否 --> F{使用哪条调用渠道}
F -- Developer API --> G[检查模型开放范围与来源限制]
F -- Vertex AI --> H[检查 ADC、IAM、项目与区域]
路径一:确认接口和模型真的可用
别根据控制台展示名或新闻里的名称猜模型 ID。Gemini Developer API 当前能看到哪些模型,应以目标项目和凭据实际返回的模型列表为准。
可以先安装 Google Gen AI Python SDK:
python -m pip install -U google-genai
然后执行最小模型列表查询:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
try:
for model in client.models.list():
print(model.name)
except Exception as exc:
print(type(exc).__name__, exc)
结果看两件事:
- 列表查询是否成功;
- 返回结果里是否真的有
gemini-3.5-flash。
如果列表查询本身就是 403,先别碰生成参数。检查对应 API 是否启用、Key 是否绑定了错误项目,以及 API 限制是否允许当前服务。
列表查询成功但找不到目标模型,也不能直接认定是 IAM 问题。模型可能还没对当前渠道、项目、账户或区域开放。
按 2026 年 11 月 5 日实时模型目录核对,本文使用的模型 ID 是:
gemini-3.5-flash
若改用 OpenRouter 或 ofox.io 这类聚合网关/中转路径做配置对照,应分别核对 base_url、model 和鉴权请求头;第三方路径的 model 值必须取自其模型目录,不能直接沿用官方 SDK 配置。
第三方聚合平台可能使用带厂商命名空间的模型名称,但不能把第三方平台的完整 ID 原样复制到 Google 官方 SDK。不同平台接受什么名称,应分别查看对应平台的实时模型目录,不要自行拼接。
路径二:检查凭据作用域有没有混用
这是个高频坑。
Gemini Developer API 通常使用:
- Google Gen AI SDK;
- API Key。
Vertex AI Gemini 通常使用:
- Vertex AI 调用方式;
- ADC 或 OAuth;
- Google Cloud IAM;
- 明确的 Google Cloud 项目和区域。
两套体系不能混着配。拿普通 API Key 套用 Vertex AI 的鉴权流程,或者把 ADC 凭据当成 Developer API 的 Key 参数,出现 403 并不意外。
要确认 Vertex AI 实际读到了哪套 ADC,可以运行:
import google.auth
from google.auth.transport.requests import Request
creds, project = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
creds.refresh(Request())
print("project:", project)
print("credential_type:", type(creds).__name__)
print("valid:", creds.valid)
creds.valid == True 只能说明令牌当前有效,不能说明该身份具备目标模型的调用权限。这两件事别混为一谈。
我还踩过一个更隐蔽的坑:终端里执行 gcloud 使用的是个人账号,服务进程读取的却是服务账号。页面上看着“我已经有角色了”,实际发请求的根本不是“我”。
路径三:检查 API Key 的来源限制
Key 本身有效,也可能因为请求来源不符合限制而被拒绝。
常见限制包括:
- HTTP Referrer 只允许指定站点;
- 服务器出口 IP 不在允许列表;
- Key 只允许调用部分 API;
- Android 或 iOS 应用标识不匹配;
- 测试环境与生产环境共用了受限 Key。
本机成功、部署后失败,先查这一条。出口 IP 变化、反向代理、云函数动态出口都容易撞上来源限制。
可以用一段不经过业务封装的最小 SDK 请求进行验证:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
try:
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="ping",
)
print(response.text)
except Exception as exc:
print(type(exc).__name__, exc)
判断方式很直接:
- 请求成功,业务代码失败:检查业务代码中的 Base URL、环境变量覆盖、SDK 版本、代理层和请求拦截器;
- 请求也返回 403:问题大概率出在 Key 限制、模型访问资格或服务端权限;
- 换一台机器结果不同:重点检查 IP、Referrer 和应用来源限制;
- 模型列表成功,但生成请求返回 403:重点检查目标模型是否对当前项目和渠道开放。
对比官方端点与 OpenRouter、ofox.io 等聚合网关/中转路径时,应固定 contents、采样参数和超时设置,并分别记录最终 model、Base URL、HTTP 状态码及响应正文,避免把配置差异误判为权限差异。
排错时可以临时创建一枚隔离测试 Key,用于判断是不是来源限制导致的问题,但不要直接取消生产 Key 的全部限制,更不要让线上凭据长期处于无限制状态。
路径四:检查账户、IAM、项目和区域
Vertex AI 最常见的预测权限之一是:
aiplatform.endpoints.predict
按 2026 年 11 月 5 日 Google Cloud IAM 文档,常用预定义角色 roles/aiplatform.user 通常包含相关调用权限。但它的权限范围可能大于单一模型调用所需。团队项目最好按最小权限原则重新评估,别为了消掉一个 403 就直接授予 Owner。
典型错误原文可能类似:
403 PERMISSION_DENIED: Permission 'aiplatform.endpoints.predict' denied on resource '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID' (or it may not exist).
角色看着已经授予,仍然返回 403,就继续核对:
- ADC 实际身份是不是你授予角色的那个身份;
- IAM 角色是不是授予到了请求中的目标项目;
- 项目是否启用了 Vertex AI API;
- 请求区域与模型可用区域是否匹配;
- 组织策略是否禁止访问对应服务;
- 当前账户或项目是否具备目标模型的访问资格;
- 请求中的模型 ID 是否准确。
“or it may not exist” 很容易把人带偏。它可能表示缺少权限,也可能是资源不可见、区域不支持、模型 ID 不正确或模型尚未开放。只凭这一句无法下结论。
辅助方案:用独立调用路径做交叉验证
如果官方调用路径持续返回 403,而你暂时判断不出是本地代码还是项目权限,可以增加一条独立路径作对照,但不要把它当成修复 IAM 的方法。
OpenRouter、Together AI 和 ofox.io 等聚合 API 路径可以用于交叉验证。需要注意,不同平台可能使用不同的模型命名规则,必须以对应平台的实时模型目录为准。
如果同一段提示词通过聚合路径能够返回,而 Google 项目仍然是 403,可以初步证明业务请求体没有明显结构问题,问题范围也就收缩到了 Google 侧的项目、身份、Key 限制、区域或模型访问资格。
反过来,如果多条独立路径都失败,则应继续检查:
- 请求体格式;
- 平台对应的模型 ID;
- 消息角色和内容结构;
- 必填参数;
- SDK 是否改写了请求;
- 代理或网关是否拦截了请求。
聚合平台的后台日志也能辅助确认请求状态、模型和 Token 消耗。不过不同平台的错误包装方式可能不同,排查时要保留原始 HTTP 状态码、错误状态和响应正文,别只看 SDK 抛出的最后一行。
常见问题 FAQ
Q:Gemini 3.5 Flash 返回 403,一定是 IAM 问题吗?
不一定。Gemini Developer API 还会受到 API Key 限制、接口未启用、模型未开放和来源限制的影响。确定使用的是 Vertex AI 后,再把 IAM 作为主要排查方向。
Q:API Key 可以直接调用 Vertex AI Gemini 吗?
不要把普通 Developer API Key 和 Vertex AI 的 ADC/OAuth 鉴权流程混用。Vertex AI 通常依赖 ADC/OAuth、Google Cloud IAM、项目和区域;Developer API 则通常使用 API Key。调用渠道、SDK、端点和鉴权方式必须配套。
Q:授予 roles/aiplatform.user 后为什么仍然 403?
检查实际 ADC 身份、目标项目、区域、Vertex AI API 启用状态、组织策略和模型访问资格。角色授错项目,或者授给了另一个账号,是最常见的情况之一。
还要注意 IAM 权限传播可能存在短暂延迟。刚修改角色后,可以等待片刻再重新获取令牌并测试,但不要把所有持续性 403 都归因于传播延迟。
Q:怎么确认当前账号能看到哪些 Gemini 模型?
Gemini Developer API 可以通过 Google Gen AI SDK执行模型列表查询;Vertex AI 则应在目标项目和目标区域查询 Model Garden 或发布者模型。不要照着展示名称自行拼接模型 ID。
Q:最小请求成功,业务代码还是 403 怎么办?
打印最终调用渠道、Base URL、模型名和凭据来源,但不要把完整 Key 或访问令牌写进日志。接着检查:
.env加载顺序;- 容器和部署平台的环境变量;
- 是否存在同名旧变量;
- SDK 默认调用渠道;
- 自定义 Base URL;
- HTTP 代理;
- 请求拦截器;
- 密钥管理服务中的旧版本凭据。
很多时候不是服务器不知道在忙什么,而是项目里还藏着第二个旧 Key。
Q:模型列表里有 gemini-3.5-flash,为什么生成请求仍然 403?
模型可见不一定等于所有方法都可调用。还要确认当前项目、账户和渠道是否具备生成权限,以及模型是否支持你正在使用的调用方式。也要检查 API Key 来源限制和组织策略。
Q:应该把生产 Key 的限制全部取消吗?
不应该。排错时可以创建短期、隔离、低权限的测试凭据进行对照,测试结束后立即撤销。生产 Key 应保留适当的 API 限制和来源限制,并定期轮换。
我的最终选择
我现在固定按这个顺序处理:
- 查询当前凭据可见的模型;
- 确认使用的是 Developer API 还是 Vertex AI;
- 用正确的模型 ID 发最小生成请求;
- 检查 API Key 的来源和 API 限制;
- 核对实际身份、项目、区域和 IAM;
- 最后再查组织策略与模型开放资格。
别一看到 403 就重建密钥,也别上来乱加角色。最小请求能直接分开业务代码问题与服务端权限问题,通常几分钟就能缩小范围。
剩下最难查的是组织策略和模型开放资格。对这类问题,目前最稳妥的办法仍然是逐项核对项目配置、实际调用身份、目标区域、模型可见性和审计日志。
386



被折叠的 条评论
为什么被折叠?



