Gemini API 返回 400 INVALID_ARGUMENT 怎么排查

读取错误体，而不是只看 HTTP 400

保留脱敏后的 error.status、message、模型、API 版本、SDK 版本和请求结构摘要。不要把 key、用户原文或完整 Authorization 头带入错误上报。将同一业务请求的原始载荷与最小官方样例分开，才能看出问题是应用参数还是基础配置。

按四层逐项定位

第一层核对 URL、API 版本和模型名称；第二层核对 JSON 根对象、必填字段和数组层级；第三层核对参数范围与模型支持的功能；第四层核对 SDK 版本及其字段命名。Google 文档特别提示，使用较新 API 版本的功能调用较旧端点会导致此类问题。

最小化复现方法

从当前官方参考的最小请求开始，在同一环境确认成功后，每次只恢复一个业务字段：输入内容、generation config、工具、结构化输出和媒体。遇到失败即保存差异。不要同时切换模型、SDK、代理和请求体，否则无法建立因果关系。

1. 官方最小请求：确认端点、版本、模型
2. 加入 contents：确认文本或多模态结构
3. 加入 generation config：逐项验证范围
4. 最后加入工具或高级特性

重试边界

Gemini 官方建议只对 429、408 或 5xx 等短暂问题执行退避；400 和 403 等客户端错误应先修复请求。把 400 交给通用重试器只会增加无效流量，还会掩盖版本迁移和字段校验问题。

修复后验收

修复完成后，分别跑最小请求、原业务请求和一个边界输入；确认错误分类、日志脱敏和用户提示没有回归。若错误仅发生于一个模型或 beta endpoint，记录它的版本与支持范围，并以官方当前参考为准，而不是复制旧示例。

400 INVALID_ARGUMENT 应该重试吗？

通常不应。Gemini 官方将 400 归为客户端错误，应先修复请求；仅在官方确认的短暂服务事件中再做受控判断。

400 一定是 API key 问题吗？

不一定。密钥问题常见于认证或权限错误；400 更常表示请求格式、字段或参数问题，应读取完整但脱敏的错误说明。