跳转至

动作响应

动作响应是 OneBot 实现收到应用端的动作请求并处理完毕后,发回应用端的数据。

格式

动作响应应表示为一个字典/映射/对象,且必须具有下面这些字段:

字段名 数据类型 说明
status string 执行状态(成功与否),必须是 okfailed 中的一个,分别表示执行成功和失败
retcode int64 返回码,必须符合本页后面所定义的返回码规则
data any 响应数据
message string 错误信息,当动作执行失败时,建议在此填写人类可读的错误信息,当执行成功时,应为空字符串

提示

若一个数据中缺失上述任一字段或类型错误,则不应认为该数据是有效的动作响应。

除此之外,若动作请求中包含 echo 字段且不是空字符串,则对应的动作响应中也应包含:

字段名 数据类型 说明
echo string 应原样返回动作请求中的 echo 字段值

例子

一个以 JSON 编码的动作响应例子如下:

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "message_id": "1234",
        "time": 1632847927
    },
    "message": "",
    "echo": "1234"
}

返回码

0 成功(OK)

当动作请求有效、动作执行成功时,返回码应为 0

1xxxx 动作请求错误(Request Error)

提示

这种错误类型类似 HTTP 的 4xx 客户端错误。

当出现动作请求无效、缺少参数、参数类型错误等情况时,返回码应为下表中的一个:

错误码 错误名 说明 备注
10001 Bad Request 无效的动作请求 格式错误、必要字段缺失或字段类型错误
10002 Unsupported Action 不支持的动作请求 OneBot 实现没有实现该动作
10003 Bad Param 无效的动作请求参数 参数缺失或参数类型错误
10004 Unsupported Param 不支持的动作请求参数 OneBot 实现没有实现该参数的语义
10005 Unsupported Segment 不支持的消息段类型 OneBot 实现没有实现该消息段类型
10006 Bad Segment Data 无效的消息段参数 参数缺失或参数类型错误
10007 Unsupported Segment Data 不支持的消息段参数 OneBot 实现没有实现该参数的语义

2xxxx 动作处理器错误(Handler Error)

提示

这种错误类型类似 HTTP 的 5xx 服务端错误。

当 OneBot 实现的动作处理器/函数在处理动作请求时发生异常或没有正确返回响应时,返回码应为下表中的一个:

错误码 错误名 说明 备注
20001 Bad Handler 动作处理器实现错误 没有正确设置响应状态等
20002 Internal Handler Error 动作处理器运行时抛出异常 OneBot 实现内部发生了未捕获的意料之外的异常

3xxxx 动作执行错误(Execution Error)

当动作请求有效,但动作执行失败时,返回码建议为下表中的一种,其中低三位可以由 OneBot 实现自行定义:

错误码 错误名 说明 备注
31xxx Database Error 数据库错误 如数据库查询失败等
32xxx Filesystem Error 文件系统错误 如读取或写入文件失败等
33xxx Network Error 网络错误 如下载文件失败等
34xxx Platform Error 机器人平台错误 如由于机器人平台限制导致消息发送失败等
35xxx Logic Error 动作逻辑错误 如尝试向不存在的用户发送消息等
36xxx I Am Tired 我不想干了 一位 OneBot 实现决定罢工

4xxxx5xxxx 保留错误段

这两段返回码为保留段,暂未使用。

6xxxx9xxxx 其它错误段

对于 3xxxx 无法涵盖的情形,OneBot 实现可以自由使用其它错误段来表示。