Sonnet 5.5升级后API返回400错误：思考模式、工具调用与历史消息适配指南

只换模型ID可能就会让原本正常的 Sonnet 5 接入报错。Sonnet 5.5 改变了支持的思考设置、强制工具选择、思考历史处理以及部分工具兼容性。升级后出现 HTTP 400应先看错误正文和实际发出的请求再决定是否修改认证或重试。本文依据 Anthropic 的 Sonnet 5.5迁移指南与变化说明核对日期为 2026 年 9 月 29 日。示例是按文档整理的请求格式不代表 Ofox 在真实 API 上复现了每种错误。401、429 或供应商特有的 404 需要分别排查。先找出不兼容的字段旧配置Sonnet 5.5的变化第一步处理thinking.type: disabled被拒绝改用between_toolseffort不高于high手动enabled搭配budget_tokens被拒绝改用支持的adaptive thinking或between_toolstool_choice.type: any或tool被拒绝改用auto由应用检查工具选择编辑历史后重放思考块可能违反对话绑定规则保持只追加历史或按文档处理应丢弃的块Claude API/Google Cloud上的computer_20251124被拒绝迁移到受支持的computer工具集并更新循环较旧的advisor模型搭配部分组合被拒绝查看支持的advisor列表computer use 这一行不能推广到所有供应商。同一官方页面说明 Amazon Bedrock 仍接受旧的computer_20251124工具。平台范围也是修复方案的一部分。谨慎替换disabled思考下面是依据文档整理的最小纯文本请求不带工具适用于原生 Claude API 的POST /v1/messages{ model: claude-sonnet-5-5, max_tokens: 1024, thinking: {type: between_tools}, output_config: {effort: high}, messages: [{role: user, content: Return a one-sentence summary of this task: verify a CSV total.}] }这只是请求体不是完整 HTTP 客户端。还需要按 Messages API要求提供认证和 API 版本请求头。凭据放在自己的环境中不要写进复制的示例或日志。between_tools关闭的是开始执行前的思考并不承诺所有工具流程都没有思考块。工具之间的进度说明仍可能使用这种块。该模式接受 low、medium、high不接受 xhigh、max也不接受display、budget_tokens等额外字段。要使用 xhigh 或 max应使用 adaptive thinking。组合不兼容时重复请求不会解决参数校验错误。替换强制工具调用后仍要检查行为把tool_choice改成auto会改变行为模型可以决定是否调用工具。在支持的工具定义里加入strict: true验证的是工具输入结构并不会强制选中该工具。应用仍要检查预期调用是否实际发生。这些 schema 功能也依赖平台迁移指南指出Amazon Bedrock 上的 Sonnet 5.5 不支持结构化输出包括 strict tool use。如果做数据提取先判断是否真的需要工具调用。结果只是数据、不是动作时结构化输出可能更合适。应测试合法输出、缺少必填信息、拒绝响应和意外的自然语言回答。请求不再报 400并不等于迁移完成。保持对话历史的一致性Sonnet 5.5 的思考块与模型及对话绑定。修改早先的系统提示词、工具定义或消息同时重放后面的思考块可能触发绑定错误。官方默认强制规则适用于指定平台上在 2026 年 8 月 31 日 00:00 UTC 或之后创建的账户较早账户和显式启用设置要另行核对。最简单的设计是只追加历史。保持返回块原样用文档规定的方法处理对话中途变更。如果确实要编辑历史应按迁移指南处理受影响的块及 beta 控制。不要把“每次都删除全部思考块”当作通用修法它会改变对话也可能丢失有用上下文。切换模型还有单独规则。目标模型无法读取的块可能被丢弃这与编辑前缀导致的绑定失败不同。应记录具体错误或转换元数据不要把所有问题统称为“invalid signature”。较早场景可参考思考块签名排错指南。HTTP成功的响应也要检查有些回归不会返回 HTTP 错误。工具调用之间较长的进度说明可能放在思考块中而 adaptive 默认显示行为会省略这些块的文本。只渲染 text 块的界面可能看似没有动静实际上请求有效。应核对 adaptive 模式的thinking.display文档或受支持的between_tools模式。还要区分拒绝响应与传输失败。文档描述了 HTTP 200 搭配stop_reason: refusal及附加详情的情况。HTTP 成功状态不能证明任务完成。应明确处理返回结果不要反复提交相同的被拒绝任务。切换生产流量前的验证保留一组小型测试输入纯文本、工具调用、多轮对话、编辑历史、流式更新和拒绝处理。核对请求格式、响应解析器、工具结果对应关系及用户可见输出。每次保存客户端版本和精确模型ID排查时保留旧接入的回滚配置。更完整的上线检查见升级决策指南CLI选模见 Claude Code设置指南。本文讨论原生 API 变化第三方网关可能增加自己的适配层和错误。