动作响应

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

格式

动作响应应表示为一个对象（object 类型），且必须具有下面这些字段：

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

提示

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

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

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

例子

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

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

返回码

0 成功（OK）

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

1xxxx 动作请求错误（Request Error）

提示

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

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

错误码	错误名	说明	备注
10001	Bad Request	无效的动作请求	格式错误（包括实现不支持 MessagePack 的情况）、必要字段缺失或字段类型错误
10002	Unsupported Action	不支持的动作请求	OneBot 实现没有实现该动作
10003	Bad Param	无效的动作请求参数	参数缺失或参数类型错误
10004	Unsupported Param	不支持的动作请求参数	OneBot 实现没有实现该参数的语义
10005	Unsupported Segment	不支持的消息段类型	OneBot 实现没有实现该消息段类型
10006	Bad Segment Data	无效的消息段参数	参数缺失或参数类型错误
10007	Unsupported Segment Data	不支持的消息段参数	OneBot 实现没有实现该参数的语义
10101	Who Am I	未指定机器人账号	OneBot 实现在单个 OneBot Connect 连接上支持多个机器人账号，但动作请求未指定要使用的账号
10102	Unknown Self	未知的机器人账号	动作请求指定的机器人账号不存在

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 实现决定罢工

4xxxx、5xxxx 保留错误段

这两段返回码为保留段，OneBot 实现不应该使用。

6xxxx～9xxxx 其它错误段

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