扣子平台调用智能体 API 返回 400 报错,请求参数和鉴权应该按什么顺序排查?

400 属于请求本身不被接受,不是服务端崩溃,应先看返回体里的错误码与 message,再按鉴权头、请求体字段、模型或智能体标识、内容长度与格式四层顺序排查。多数情况是 Authorization 头缺 Bearer 前缀、bot_id 与模型名混用,或参数类型写错。

扣子平台 API 调用返回 400,说明请求在服务端校验阶段就被拒绝了,排查重点不在网络连通性,而在请求头、请求体字段与所调对象(智能体还是模型)是否匹配;如果你的调用经过了自建网关或中转层,还要先确认网关没有改写参数。拿到 400 后第一件事不是换 Key,而是把响应体完整打印出来——扣子的 400 响应通常带错误码与 message,那一行往往直接指出是哪个字段不合法。 400 与 401、403、404、429 的分工要分清:401 是身份没通过,403 是权限不足,404 是路径或对象不存在,429 是触发限流,只有 400 是「请求语义不被接受」。这意味着换一个新 Token 大概率无效,反复重试也不会自愈,重试策略只对 5xx 和 429 有意义。把 400 当网络抖动处理,是接入阶段最常见的误判。 第一层排查鉴权头。Authorization 必须是 Bearer 加空格再加访问令牌,缺前缀、多空格、把令牌写进 query 参数都会直接 400 或 401。很多人从控制台复制的令牌带了换行或不可见字符,粘贴到配置文件里看不出异常。做法是打印请求头的字符长度并断言前缀,同时在本地环境变量中避免引号与换行被一并写入。 第二层排查请求体字段名与类型。扣子的对话类接口对 bot_id、user_id、query、stream 等字段的命名与类型有明确约定,把数字型 ID 写成字符串、把布尔值 stream 写成字符串 "true"、把对话内容放进错误的对象层级,都会返回 400。稳妥做法是用官方示例的最小请求体跑通一次,再逐步添加字段,而不是先写完整业务参数再回头删。 第三层确认调用的对象类型是否搞混。调智能体要用智能体标识,调模型要用模型名,两者不能互相顶替;把方舟侧的模型 endpoint 填进智能体的 bot_id 位置,是典型的 400 来源。同样,把工作流、插件、知识库的标识沿用到对话接口也会失败。排查时先确认这条请求打的是哪一类接口,再核对标识来自控制台哪个页面。 第四层看内容本身是否越界。请求体超过平台体积上限、图片或文件以 base64 塞进文本字段、多轮对话历史格式不规范(role 取值不合法、content 为空数组),都可能被判为 400。内容类问题的隐蔽之处在于字段名都对,只是值不合规。做法是先把历史消息裁剪到最近两三轮,把附件改为平台支持的上传方式后再试。 如果调用链路里存在自建网关、SDK 封装或第三方中转层,必须把旁路验证做掉。用 curl 或最小脚本直连扣子官方域名复现同一个请求,能通就说明问题在中间层:常见的是网关把 JSON 里数字转成字符串、把 stream 参数吃掉、或者自己拼了一个多余字段。把中间层日志里的出站请求体与官方示例逐字段对比,比在业务代码里猜要快得多。 智能体客服这类业务在接入期特别容易踩 400,因为一次会话里既有对话内容,又有变量、文件、卡片等多类参数。建议把通话链路拆成三步验收:先只发一句纯文本、不带变量;再加会话变量;最后加附件与流式。每步都留一份可回放的请求样本,出问题能一步定位到是哪类参数引入的。这套样本在后续换模型、换版本时也是回归测试的基础。 从运营角度看,400 的排查成本主要花在信息缺失上。让每次失败都记录响应体的错误码与 message、请求接口路径、请求体摘要(脱敏后)和请求 ID,形成一张可检索的表,同类问题第二次出现时就能几分钟内定位。只记录「接口报错」四个字的日志,等于把排查成本推给了下一个人。 把 400 的处理机制沉淀成规则会更省事:客户端对 4xx 一律不重试,直接落错误事件并提示用户改写输入或联系人工;对 429 与 5xx 才做指数退避。智能体客服场景下,一次 400 若被静默重试三次,用户看到的是长时间无响应,体验损失比错误本身更大。 需要说明适用边界:以上顺序针对的是对话与智能体调用类接口的 400;如果错误码是 401、403、404、429,排查路径完全不同,不要套用。另外,平台接口字段与限制会随版本调整,具体参数名、体积上限与鉴权方式以扣子官方文档和控制台说明为准,本文提供的是一套可复用的排查次序,而不是固定字段清单。 最后给一个可落地的判断标准:能在五分钟内复现并定位到具体字段的 400,属于接入配置问题,靠自查解决;同一请求用官方最小示例也失败、且响应体没有可读 message 的,才值得提交工单并附上请求 ID 与完整响应。把这条界线画清楚,团队就不会把每个 400 都升级成外部支持请求。