API Error 400:system content must contain at least one block
「system content must contain at least one block」是什么意思
Claude Messages API 报错 api error: 400 messages.1: system content must contain at least one block,表示请求已经打到 Anthropic,但某条消息上的 system 字段(常见是多方组装里的 index 1)是空的或内容不合法。接口要求:要么不要带 system,要么至少带 一个内容块(通常是 text block)。
这是请求体形状问题,不是宕机。同类 400 见 Claude API Error 400。
常见触发写法
SDK、网关、手写 curl 里最常见的原因:
- 空 system 字符串 — 模板渲染后变成
system: ""或system: []。 - 空 content — 有
system对象但没有content,或content: []。 - 看错 index — 有的封装把 system 放在
messages[1];报错里的.1指向字段路径,不是「HTTP/1.1」。 - 条件系统提示 — 功能开关关掉了提示,却仍发送
system键。 - 代理改写 — LLM API Gateway 或 Claude API Proxy 把 system 掏空,却留下字段。
修复清单(按顺序做)
- 把模板渲染后、真正出站的 JSON 打出来。
- 若
system为空,整键省略,不要发""/[]。 - 需要系统提示时,至少发一个非空 text block。
- 在 CI 里拦截:存在
system但块数为 0 或文本空白的出站请求。 - 只在镜像/代理里复现时,对照直连 Messages 请求;形状通过后再看 超时 / 529 overloaded 等其它错误。
心智模型:
- 不用系统提示就省略
system。 - 要用时,
system至少 1 个有真实文本的 block。
SDK 与网关注意点
- 官方 SDK 常把字符串
system转成 blocks;空字符串在某些版本仍可能序列化成非法空列表——升级并核对线上报文。 - 自研 agent 若把
role: system塞进messages[],更容易出现messages.N类校验错误;Messages API 更偏好顶层system。 - 多租户网关 在租户模板为空时,应删除
system键,而不是转发空内容。
如何确认已修好
用同一轮 user 再发:
- 不带
system,或 - 带一个非空 text 的
system
形状正确时应返回 200(或变成鉴权/限流等另一类错误)。若仍是 400 但文案变了,说明本规则已过,去读新的 error.message,别盲目重试同一空 system。
FAQ
这是 Anthropic 故障吗? 几乎不是。空 system 内容属于请求校验失败。
为什么是 messages.1? 它标出校验失败的字段路径。去序列化 JSON 里看对应下标。
只发空格当 system 可以吗? 别依赖。给真实指令,或省略 system。