适用场景：请求没有跑到模型能力层
400 错误通常表示服务端认为请求格式不合规。它和 401 鉴权失败、403 权限不足、429 限流不同。常见表现包括：本地 curl 可以成功，前端 fetch 失败；换成流式输出后失败；多模态字段一加就失败；通过 CCSwitch 配置或网关转发后，原本可用的参数被改名或被丢弃。此时直接更换 Key 或供应方，往往会掩盖真正问题。
排查前先准备一个最小请求，只保留模型名、一条用户消息和必要 header。永沃云枢建议把复杂任务拆成“最小文本请求、带参数请求、带工具请求、带文件或图片请求”四层，逐层增加字段。这样 Codex 接入和开发者 AI 调用都能复用同一套诊断样本。
先把 400 分成三类
第一类是协议层错误，例如 Content-Type 没有设置为 application/json，请求体被表单编码，或代理把换行、引号处理坏了。第二类是 schema 层错误，例如字段名拼错、数组和对象位置反了、工具定义缺必填项。第三类是模型参数层错误，例如目标模型不支持某个参数、上下文长度超出、流式开关与响应解析不匹配。
如果使用 CCSwitch 配置，还要增加第四类：转发层改写。界面里看到的模型别名，可能会被映射成实际模型名；网关也可能补默认参数、删除未知字段或改变路径。对 AI API 接入而言，必须保存“应用发出的请求”和“网关实际转发的请求”两份视图，不能只看其中一个。
操作步骤：用最小样本逐项加字段
- 记录失败请求的 URL、方法、状态码、错误对象和 request_id。敏感 Key 只保留尾号，不写入文档。
- 用最小文本 payload 复现：模型名、messages 或 input、一个短提示词。成功后再加 temperature、max tokens、stream 等参数。
- 检查 header。Content-Type、Accept、Authorization、组织或项目 header 要与目标接口文档一致；不要让前端和后端各补一份互相冲突的 header。
- 检查 JSON。用本地解析器验证请求体能被解析，字段类型正确，字符串没有被二次转义，中文没有变成问号或乱码。
- 若经过 CCSwitch 或代理，打印脱敏后的转发摘要：base_url、模型映射、路径、启用参数和被删除字段。不要打印完整 Key。
- 每次只改一个变量。参数变更后保存成功和失败样本，形成一张小表，避免靠记忆判断。
排错路径：从错误文本反推字段
如果错误提示类似“unsupported parameter”，优先查模型能力，不要查网络。若提示“invalid type”，比较实际 JSON 中该字段是字符串、数字还是数组。若提示“missing required field”，先看字段是否在错误的嵌套层级。若没有可读错误文本，说明网关或 SDK 可能吞掉了原始响应，需要临时打开更详细的脱敏日志。
流式输出导致 400 时，检查 stream 字段、响应格式和前端解析是否成套。多模型路由里，同一参数可能只对部分模型有效；这时应把能力差异写进 profile，而不是让业务代码盲发所有参数。相关文章可参考工具能力矩阵检查和JSON 解析契约。
常见问题 / 避坑
不要把 400 当成供应方不可用。更换接口前，应证明最小请求、header 和 payload 都正确。不要把浏览器 Network 面板里的美化结果当原始字节，必要时导出 curl 或在后端记录脱敏请求体。不要在一次修复里同时改模型名、路径、参数和 SDK 版本，这会让结论不可复盘。
AI 自动化办公的批量任务尤其要做预检。生成邮件、整理表格或读取附件前，先用一条低风险样本跑通 payload，再放大到批量。Codex 可以帮助生成请求样本和检查差异，但关键字段规则仍应由配置或代码固定。
检查清单
- 最小文本请求可独立成功，复杂字段是逐项增加的。
- Content-Type、Accept、Authorization、项目 header 与目标接口匹配。
- payload 能被本地 JSON 解析，字段类型和嵌套层级正确。
- 模型参数与目标模型能力一致，流式、工具和多模态开关没有混用。
- 网关或 CCSwitch 的实际转发摘要已脱敏记录。
- 延伸阅读：UTF-8 与流式分片排查、trace_id 路由日志、AI API 专题、CCSwitch 专题。
验收标准：成功请求和失败请求都要可解释
修复 400 后，至少保留四个样本：最小成功请求、带业务参数的成功请求、一个故意错误的参数样本，以及一条真实业务链路。成功样本证明格式正确，失败样本证明错误会被清楚返回，而不是被前端吞掉或变成笼统提示。这样下次调整模型、SDK 或网关时，团队能快速判断是哪一层发生变化。
如果请求要进入批量任务，还应增加一条空值样本和一条超长输入样本。预检阶段暴露问题，远比任务跑到一半再补偿便宜。
FAQ：400 修好后还要不要做回归
要。400 修复通常会碰到请求构造代码、模型参数或转发配置，这些位置影响面很广。至少回归一个普通文本请求、一个流式请求、一个错误参数样本和一个真实业务样本。验收标准不是“这次不报错”，而是请求格式、错误提示和日志能稳定说明发生了什么，后续模型调用管理才不会再次靠猜。