Gemini 3.6 Flash 常见报错及解决方法

文章导读
遇到 Gemini 3.6 Flash 报错,先不要急着改代码。多数报错落在四个层面:请求没到服务端、参数被拒绝、触发了限流配额、生成结果被截断或过滤。下面按“现象 -> 检查点 -> 处理动作 -> 验证信号”给出一套分支排查,先处理能稳定复现的,再处理偶发的。
📋 目录
  1. 一 先判断错误发生在哪一层
  2. 二 常见 HTTP 状态码排查清单
  3. 三 参数和请求体问题:最小复现法
  4. 四 限流和配额:不要用固定间隔重试
  5. 五 输出被截断或安全过滤
A A

遇到 Gemini 3.6 Flash 报错,先不要急着改代码。多数报错落在四个层面:请求没到服务端、参数被拒绝、触发了限流配额、生成结果被截断或过滤。下面按“现象 -> 检查点 -> 处理动作 -> 验证信号”给出一套分支排查,先处理能稳定复现的,再处理偶发的。

先判断错误发生在哪一层

打开日志,看报错来源。如果来自 SDK 的“网络超时”,和来自服务端的“400 Bad Request”是完全不同的排查路径。可以用一句话判断:

  • 请求发出后立刻报错,通常是认证、请求格式或路径问题;
  • 请求发出后等待很久再报错,通常是超时、限流或模型生成阶段问题;
  • 同一段代码时好时坏,先怀疑限流、临时网络或配额波动。

给日志加上时间戳、模型名、请求 ID。如果没有请求 ID,至少记录完整请求体和响应体,否则很难定位。

常见 HTTP 状态码排查清单

  • 401 Unauthorized:检查 API Key 是否正确,请求头是否真的带上了认证信息。处理动作:在测试环境打印请求头,确认 Key 没有拼写错误、没有多余空格。验证信号:换成手动从控制台复制的新 Key 后,请求不再返回 401。
  • 404 Not Found:检查模型名和接口路径。Gemini 3.6 Flash 这类模型名经常带版本后缀,少写一个点或大小写不对都会 404。处理动作:确认模型名与当前服务端可用列表一致,不要照抄旧项目配置。
  • 400 Bad Request:检查请求体里的字段名、类型、枚举值。最常见的是把字符串传给数值字段,或者 messages / contents 结构不完整。处理动作:用最小请求体逐步加字段,定位出错字段。
  • 429 Too Many Requests:触发限流或并发配额。先看响应体里的 Retry-After 头,没有就采用递增退避,例如固定退避 5 秒、15 秒、30 秒重试,最多 3 次。不要把重试逻辑放在每次请求里直接循环。
  • 500 / 503:服务端临时问题。不要立刻改代码,先确认是偶发还是持续。如果是持续 503,检查是否触发了某种资源限制,例如请求体过大或输出长度上限。

参数和请求体问题:最小复现法

遇到 400 报错,把请求体压缩到最小,别带一堆无关字段。下面是一个可以直接用于测试的请求体骨架,具体字段以你当前 SDK 的模型签名为准:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "你好,用一句话介绍自己。" }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 100,
    "temperature": 0.2
  }
}

先只发这个请求。如果成功,再手动添加 systemInstruction、工具定义、候选数等字段,每加一个就重放一次,直到复现失败。这样能快速确认是哪个参数不受支持,还是字段嵌套层级不对。

另外,部分报错会在消息里直接给出字段路径,例如 contents.0.parts。不要只看最后一行,把完整响应体保留下来。

Gemini 3.6 Flash 常见报错及解决方法

限流和配额:不要用固定间隔重试

429 报错的处理边界是“只对可重试的失败重试”。如果响应里带有重试时间,遵循它;如果没有,采用递增退避。下面是一个伪代码流程:

for attempt in 1..3:
    response = call_gemini(payload)
    if response.status == 429:
        wait = base * (2 ** attempt)  # 例如 base=2s,得到 2s、4s、8s
        sleep(wait)
        continue
    if response.status == 400:
        save_payload_for_debug()
        raise  # 参数错误改多少次也不会成功,直接进日志
    break

注意:请求并发较高的场景里,重试可能会加剧限流。建议在发请求前先做本地队列,限制最大并发数,而不是等 429 出现后再重试。验证信号是:连续运行 10 次测试请求,不再出现 429,且请求间隔平稳。

输出被截断或安全过滤

这类问题没有 HTTP 错误码,但响应里的 finish_reason 能提示原因。常见的三个现象:

  • 输出长度固定在一段后中断,检查 finish_reason 是否为 MAX_TOKENS。处理动作:调大 maxOutputTokens,或把提示词改短,给生成留空间。
  • 输出内容有遮挡、空段落,检查 promptFeedback.blockReason 或 safetyRatings。处理动作:调整提示词措辞,避免触发内容安全过滤。
  • 返回正常但内容不完整,检查是否使用了流式接口,流式中断时最后一段可能会丢失。处理动作:在流式响应里累计所有分片,并校验最后的 finish_reason。

验证信号:修改后重跑同一条用例,对比输出长度和 finish_reason。示例:把 maxOutputTokens 从 100 改成 500,并在日志里打点记录 token 数,能确认是长度限制还是过滤导致的截断。