Gemini API 常见报错排查：401、404、429、地区限制（2026）

Gemini API 的报错看起来名目很多，实际排起来大多落在四类：身份不对、地址不对、额度不够、网络到不了。真正由模型本身导致的问题反而少。

本文按错误码逐类拆解，给一套从最小请求开始的排查顺序。遇到问题时先保存完整错误 JSON，再按顺序核对，不要同时改 Key、地址和模型。

说明：Google、Gemini 是其权利人的商标。本文以 2026 年 10 月的常见接口形态为例，接口版本、配额和地区政策以官方文档与站内模型价格为准。

一、先学会看错误体

Google API 的错误通常返回 JSON，关键字段有三个：

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code 是 HTTP 状态码，status 是机器可读的错误类型，message 里往往包含具体原因，details 里可能有配额 ID 和建议重试时间。排错时三样都要看，只看“429”会漏掉“到底是分钟限流还是日额度用完”。

状态码	常见 status	大致方向
401	UNAUTHENTICATED	Key 缺失、无效或放错位置
403	PERMISSION_DENIED	项目未启用、权限或地区受限
404	NOT_FOUND	模型名、接口路径或版本不对
429	RESOURCE_EXHAUSTED	速率、并发或配额超限
400	INVALID_ARGUMENT / FAILED_PRECONDITION	参数错误、地区不支持、前置条件不满足
500/503	INTERNAL / UNAVAILABLE	上游临时故障，通常可退避重试

二、401：Key 无效或鉴权方式不对

401 的核心是“服务端不认你的身份”。常见原因有：

• 请求里根本没带 Key，或者环境变量为空。
• 原生接口用了 Authorization，而不是 x-goog-api-key。
• OpenAI 兼容接口用了 x-goog-api-key，而不是 Authorization: Bearer。
• Key 前后有空格、换行，复制时带进了引号。
• Key 已被删除、轮换，或所属项目被停用。
• 把网关 Key 发到了 Google 官方地址，或反过来。
• Key 设置了 API 限制，不允许调用 Gemini API。

先用一条最小请求确认：

export GEMINI_API_KEY="你的密钥"

# 原生 Gemini 接口
curl "https://generativelanguage.googleapis.com/v1beta/models/<模型ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"只回复 OK"}]}]}'

# OpenAI 兼容接口
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<模型ID>","messages":[{"role":"user","content":"只回复 OK"}]}'

两条命令对应两套鉴权。哪条能通，就说明你的 Key 和地址属于哪套体系；混用时出现 401，不是 Key 坏了，而是组合错了。

三、404：模型名、路径或版本不对

404 不一定是“模型不存在”。常见情况包括：

1. 模型 ID 拼错，或者用了控制台显示名而不是 API 标识。
2. 模型不属于当前 API 版本，例如把只在新版开放的模型发到旧版路径。
3. Base URL 多写或少写 /v1、/v1beta，路径拼接后变成不存在的地址。
4. 地址末尾多了斜杠，客户端又拼了一次路径。
5. 通过网关调用时，该模型没有在当前分组或套餐里开通。
6. 用了聊天接口去调图像生成或其他专用接口。

排查时先列出当前 Key 可用的模型：

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

如果列表里有目标模型，再核对请求路径；如果列表里没有，先解决模型开通或权限问题。通过网关调用时，以网关文档给出的模型 ID 和 Base URL 为准，不要拿官方模型名直接套。

四、429：先分清限流还是额度用完

429 是最容易被误判的一类。它至少包括三种情况：

类型	典型特征	处理方向
分钟级限流	短时间并发高，错误集中在几秒内	降低并发，退避重试
日额度用完	当天调用量达到上限，持续失败	等重置、升级配额或换方案
项目级配额	多个服务共用同一项目，互相挤占	拆项目、拆 Key、单独配额

错误体里的 details 通常会给出配额 ID 和建议重试时间。不要看到 429 就立刻重发，重试风暴会让情况更糟。一个可用的退避逻辑：

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<模型ID>:generateContent"
    headers = {
        "x-goog-api-key": "你的密钥",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("重试次数用尽")

重试只解决临时拥塞，解决不了额度耗尽。生产环境还要加超时、熔断和备用模型，否则一个 429 会拖垮整条链路。

五、地区限制：为什么国内直连会失败

Gemini API 只在部分国家和地区提供服务。请求出口落在不支持的地区时，常见表现有三种：

• 连接超时或 TLS 握手失败，通常是网络路径不通。
• 返回 400 FAILED_PRECONDITION，文案包含 location is not supported 一类提示。
• 返回 403 PERMISSION_DENIED，可能与项目、账单或地区权限有关。

这里有两个容易混淆的概念：账号注册地区和请求出口地区。即使账号本身可用，服务器部署在不支持的地区，请求仍可能被拒绝；反过来，本机代理能打开网页，也不代表 API 请求走了同一条线路。

处理顺序建议如下：

1. 确认请求是从本机、容器还是服务器发出，找到真实出口 IP。
2. 核对出口地区是否在官方支持列表内。
3. 检查云服务器的区域选择，必要时换到支持的区域。
4. 如果业务主要在国内，评估通过合规网关接入，统一处理网络与账单。
5. 不要把“换 IP”当成唯一方案，先确认服务条款和当地法规要求。

六、其他高频错误

现象	常见原因	处理
400 INVALID_ARGUMENT	JSON 结构错误、角色顺序不对、图片格式不支持	用最小请求逐步加字段
400 FAILED_PRECONDITION	地区不支持、账单未开通、前置条件缺失	查地区、账单和项目状态
403 PERMISSION_DENIED	API 未启用、Key 限制、项目权限不足	在控制台启用并核对权限
500 INTERNAL	上游内部错误	退避重试，记录请求 ID
503 UNAVAILABLE	上游过载或维护	退避重试，切换备用模型
有响应但无内容	安全策略拦截、输出被截断	看 blockReason 和 finishReason
输出中途停止	达到最大输出 Token	提高上限或缩短输入

“有响应但没内容”经常被当成故障，其实是安全过滤或长度限制。先看返回里的 promptFeedback.blockReason、finishReason 和 usageMetadata，再决定是改提示词还是调参数。

七、推荐的排查顺序

1. 保存完整错误 JSON、请求时间、模型 ID 和请求 ID。
2. 用 curl 发一条最小请求，排除客户端和 SDK 的干扰。
3. 核对三件事：Base URL、鉴权头、模型 ID。
4. 换一个已知可用的模型，判断是模型问题还是链路问题。
5. 查看配额、账单和项目状态，区分 429 与 403。
6. 确认请求出口地区和网络路径。
7. 最后再检查客户端配置、代理设置和代码里的重试逻辑。

一次只改一个变量。否则即使恢复了，也不知道是哪一步修好的，下次还会踩同一个坑。

八、常见问题

401 和 403 有什么区别？

401 是“身份没通过”，优先查 Key、鉴权头和地址是否匹配；403 是“身份通过了但没权限”，优先查 API 是否启用、项目权限、Key 限制和地区政策。

429 等几分钟再试就行吗？

要看配额类型。分钟级限流退避后通常能恢复；日额度用完要等重置或提升配额。先读错误体里的配额 ID 和重试建议，不要盲目重发。

地区限制换个 IP 就能解决吗？

不一定。要看真实出口地区、账号状态和服务条款。企业场景更稳妥的做法是选择支持的区域部署，或通过合规网关统一接入。

官方地址能通，换成网关就 404，是谁的问题？

先核对网关的 Base URL 和模型 ID。网关的模型命名、路径和可用范围可能与官方不同，不能直接套用官方请求。用网关文档的最小示例逐项替换。

怎么避免重试把成本放大？

设置最大重试次数、指数退避和超时；对 429 单独处理；对非幂等请求加去重；在网关侧设预算上限和告警。

下一步

Gemini 报错排查的关键，是先分清“鉴权、路径、配额、网络”四类，再用最小请求逐项验证。需要统一入口、减少国内直连的不确定性，可以先注册中商起航 AI 网关，模型、配额与价格以模型价格页为准。

相关阅读：

• Gemini API Key 获取教程：AI Studio、配额与国内接入
• Gemini API 中转：国内访问、配额与替代方案