扣子平台 API 调用返回 400，该按什么顺序排查鉴权、参数和版本？

扣子平台 API 返回 400，是请求本身没有通过服务端的结构校验，排查顺序应固定为：先读响应体里的 code 与 message，再核对鉴权头与 Content-Type，然后校验 JSON 字段的类型与必填项，最后对齐接口版本与智能体的发布状态。这套顺序只对请求侧错误有效；域名解析失败、连接超时和 5xx 不属于 400 的排查范围，先归类再动手，能省掉大半无效操作。 400 与 401、403、404、429 的分工要先分清，否则会把参数问题当成权限问题反复换密钥。401 指向凭据缺失或失效，403 指向凭据有效但无权访问该资源，404 多为路径写错，429 是触发限流，5xx 才是平台侧问题。把 HTTP 状态码和响应体里的业务 code 一起记下来，是后续定位的唯一锚点，只看「调用失败」四个字等于没有信息。 排查的第一步不是改代码，而是拿到未经 SDK 包装的原始响应。不少 SDK 会把所有非 2xx 统一抛成一个异常，把 code、message、请求 ID 全部丢掉，导致只能靠猜。建议在调用层打印完整请求 URL、脱敏后的请求头、请求体的原始字符串和响应体全文，并保留最近若干次失败样本，问题基本能在这批样本里收敛。 鉴权头格式错误和 Content-Type 缺失，是 400 里最常见也最容易被忽略的两类。Authorization 必须是 Bearer 加一个空格再加令牌，令牌前后多一个空格、一个换行，或者从文档复制时带上了引号，都会被判为非法头。Content-Type 应显式写成 application/json，部分客户端在 GET 带 body 或以表单方式提交时默认发成表单类型，服务端解析不了请求体就会直接拒绝。 字段类型不匹配比字段缺失更容易触发 400，因为缺失往往有默认值处理。布尔值写成字符串、数字 ID 外面加了引号、枚举值大小写不一致、该传 null 的位置传了空字符串，都属于结构合法但语义非法的请求。做法是拿官方接口文档的字段表逐项对照类型，特别注意可选字段在「不传」和「传空」之间的差别，多轮对话里的会话标识尤其容易踩这个坑。 请求体的字符编码问题在中文场景下出现频率很高，手工拼接 JSON 是最典型的诱因。用字符串模板拼请求体，遇到引号、反斜杠、换行符就会破坏结构，服务端解析失败直接返回 400；中文、emoji 和富文本内容还必须确保按 UTF-8 发送，而不是本地默认编码。正确做法是用语言自带的序列化库构造请求体，并在发送前打印一次最终字符串做肉眼校验。 涉及多轮对话与流式输出的接口，参数组合的自洽性要单独检查。开启流式时，请求体里与之配套的字段要同时给对，客户端也要按流式方式读取响应，否则会出现「请求已经发出去了但解析失败」的假象。会话续接场景下，会话标识只能来自上一次响应的返回结果，自己拼一个或者跨智能体复用，都会在下一轮变成 400。 接口版本与智能体发布状态是两个独立维度，不要混在一次排查里。同名字段在不同版本中可能改名或改类型，请求体按新版本写、路径却指向旧版本，必然报错，反过来也一样。智能体没有发布到 API 渠道、调用的是草稿版本，通常表现为权限类错误而不是 400，看到 400 时先别急着改发布配置，先把请求体对齐。 定位 400 最快的工程手段是最小请求体加逐字段二分，而不是逐行读代码。先用只有必填字段的最小请求打通一次，确认鉴权、路径、版本三项没问题，再把业务字段一组一组加回去，哪一组加进去开始报 400，问题就在那一组里。官方提供的接口调试工具可以作为对照基准，把调试工具里成功的请求原样抓下来，和自己的请求逐项比对请求头与请求体，差异通常一眼可见。 生产环境的正确处理方式是在网关层拦住 400，而不是让它打到终端用户。智能体客服场景里，一次 400 会直接变成用户看到的「服务异常」，正确做法是在调用层做请求体的 schema 校验和字段白名单，把平台返回的 code 映射成内部错误类型，对用户侧统一降级成兜底话术并转人工。400 不应进入自动重试队列，重试改变不了请求结构，只会放大调用量和账单。 把 400 的排查经验固化成监控项，比事后翻日志更有价值。按接口维度统计 400 的占比、按字段维度记录首次出现的错误 message，配合请求样本采样，能在平台调整字段或文档更新时第一时间发现异常。需要提醒的是，接口规范和字段说明会随版本变化，遇到集中出现的 400，先查一次官方更新说明，再怀疑自己的代码。