Skip to content

错误码 ​

所有错误都收敛成 OneBot 响应,不向外抛。

json
{ "status": "failed", "retcode": 100, "data": null, "wording": "群号不存在", "echo": "1" }

码表 ​

ts
const RETCODE = {
  ACTION_FAILED: 100,
  INTERNAL_ERROR: 1200,
  BAD_REQUEST: 1400,
  UNKNOWN_ACTION: 1404,
} as const;
retcode常量含义排查方向
0—成功—
100ACTION_FAILED业务失败QQ 侧拒绝 / 目标不存在 / 权限不足。看 wording
1200INTERNAL_ERROR内部错误框架 bug 或未预期的异常
1400BAD_REQUEST参数错误缺必填、类型不对、值越界。看 wording
1404UNKNOWN_ACTION不支持的 action见下

1404:不支持的 action ​

这个码有三个来源,含义不同但客户端处理方式相同(都是「这条命令用不了」):

  1. action 名拼错 —— 检查动作列表;
  2. 后端能力不足 —— action 存在但没注册。启动日志里的 actions: N 与文档总数不一致时 就是这个原因;

怎么区分

1404 的 wording 会带具体 action 名。结合启动日志能判断是哪一类:

text
08:30:00 INFO  [cli] bot 已上线 {"uin":"…","onebot":{"port":6700,"actions":N}}

N 小于文档里的总数(214)就说明有 action 因后端能力不足被跳过了。 具体跳过了哪些,看 adapter.skipped() 或 --verbose 日志。

1400:参数错误 ​

ParamError 的语义始终是 1400,不因抛出位置不同而改变。

json
{ "status": "failed", "retcode": 1400, "data": null, "wording": "group_id 必须是正整数" }

wording 一定指出是哪个字段 —— 只说「参数错误」等于没说。

需要 ctx 才能判定的参数错误

有些校验只能在 run() 里做(如「message_id 与会话不匹配」)。这类也抛 ParamError, 所以同样是 1400,不会变成 100。

100:业务失败 ​

参数没问题,但 QQ 拒绝了。常见原因:

场景可能原因
发消息失败不是好友 / 不在群里 / 被禁言 / 账号风控
群管理操作失败权限不足(不是管理员 / 群主)
撤回失败超过撤回时限 / 不是自己的消息 / 没有管理权限
文件操作失败文件名非法 / 空间不足 / 文件不存在

wording 是原始错误信息,多数是中文,可直接展示给用户。

1200:内部错误 ​

正常情况下不该出现。遇到时请带上完整日志提 issue:

  • wording;
  • 触发的 action 与参数;
  • --verbose 下的日志。

鉴权失败 ​

鉴权失败不是上述任何一个码,而是在握手阶段就拒绝,根本建立不了连接:

场景表现
WS token 错握手响应 401 Unauthorized
WS 路径不合法握手响应 404 Not Found
HTTP token 错HTTP 状态码,非 OneBot 响应体

不会走到 OneBot 响应层

WsServerAdapter 用 verifyClient 在升级前校验,所以客户端看到的是 HTTP 层错误, 不是 { status: 'failed' }。

关闭码 ​

码含义触发场景
1008policy violation角色不接受 action(Event 角色收到 action);慢客户端
1009message too big入站单帧超过 maxPayloadBytes(由 ws 库产生)
1012service restart服务端下线

优雅关闭实际是 terminate()

WsServerAdapter.stop() 用 terminate() 而不是 close() —— close() 要等对端回 close 帧,客户端不配合时会挂住。所以客户端多数情况下看到的是连接直接断开, 而不是收到 1012 帧。

1012 常量已定义,但当前不主动发送。

单帧超限 ​

入站单帧超过 maxPayloadBytes(默认 100 MiB)→ 连接被关闭(ws 库以 1009 结束)。

大文件走 URL

超过 100 MiB 的内容(整段无损语音、大视频)应当传 URL 让框架自己去取, 不要塞进一帧。

慢客户端 ​

服务端到客户端的缓冲(bufferedAmount)超过 8 MiB → 连接以 1008 关闭。

这是有意的:无限排队会吃内存,一个慢客户端能拖垮整个进程。断掉让它自己重连更好。

响应形状汇总 ​

ts
interface ApiResponse {
  status: 'ok' | 'failed';
  retcode: number;
  data: JsonValue;          // 失败时恒为 null
  echo?: JsonValue;         // 传了就原样回传,没传就没有这个键
  wording?: string;         // 仅失败时出现
  message?: string;         // 流式接口用,普通响应不带
  stream?: string;          // 流式接口用
}

流式接口尚未实现

message / stream 两个字段是预留给流式 action 的,当前没有任何 action 使用它们。

版本未定(0.0.0 是占位);文档与代码同步演进,以主仓为准