Skip to content

MQTT 客户端错误码

对于使用 MQTT 协议接入的设备,服务端常见错误码说明如下。

MQTT v3.1.1

MQTT v3.1.1 协议只有 10 种返回码,这些返回码所能表示的含义很少,且相同的返回码的值在不同的报文中可以有不同的含义。

CONNACK 报文

在 CONNECT 报文中只有 6 种返回码,只有当服务器发回的 CONNACK 报文的返回码为 0 时才表示连接建立成功。

返回码描述
00x00 接受连接接受连接
10x01 拒绝连接,不支持的协议版本服务器不支持该客户端请求的 MQTT 协议
20x02 拒绝连接, 拒绝的客户端 ID客户端 ID 是正确的 UTF-8 字符串,但是不被服务器允许
30x03 拒绝连接,服务器不可用网络连接已经建立,但是 MQTT 服务不可用
40x04 拒绝连接,损坏的用户名或密码在用户名或密码中的数据是错误格式的
50x05 拒绝连接,未授权客户端的连接未被授权
6-255预留给将来使用

SUBACK 报文

SUBACK 报文只有四种返回码,除了返回码 0x80 表示失败,其他返回码都表示订阅成功, 3 个值 0, 1, 2 分别代表订阅接收到的消息的最大 QoS 值。

返回码描述
00x00 成功最大允许 QoS 0 的消息
10x01 成功最大允许 QoS 1 的消息
20x02 成功最大允许 QoS 2 的消息
1280x80 失败失败

MQTT v5.0

MQTT v5.0 协议将返回码改名成了原因码,增加了用于表示更多类型的错误的原因码。下表是原因码列表,分别表示的是原因码的值以及包含原因码的控制报文:

十进制十六进制名称报文
00x00成功 (Success)CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH
00x00准许 QoS 0 (Granted QoS 0)SUBACK
10x01准许 QoS 1 (Granted QoS 1)SUBACK
20x02准许 QoS 2 (Granted QoS 2)SUBACK
40x04以遗嘱消息断开连接 (Disconnect with Will Message)DISCONNECT
160x10没有匹配的订阅者 (No matching subscribers)PUBACK, PUBREC
170x11没有订阅 (No subscription existed)UNSUBACK
240x18继续认证 (Continue authentication)AUTH
250x19重新认证 (Re-authenticate)AUTH
1280x80未指定错误 (Unspecified error)CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT
1290x81畸形报文 (Malformed Packet)CONNACK, DISCONNECT
1300x82协议错误 (Protocol Error)CONNACK, DISCONNECT
1310x83实现特有错误 (Implementation specific error)CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT
1320x84不支持的协议版本 (Unsupported Protocol Version)CONNACK
1330x85客户端标识符无效 (Client Identifier not valid)CONNACK
1340x86错误的用户名和密码 (Bad User Name or Password)CONNACK
1350x87未授权 (Not authorized)CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT
1360x88服务器不可用 (Server unavailable)CONNACK
1370x89服务器繁忙 (Server busy)CONNACK, DISCONNECT
1380x8A禁止访问 (Banned)CONNACK
1390x8B服务器关机中 (Server shutting down)DISCONNECT
1400x8C错误验证方法 (Bad authentication method)CONNACK, DISCONNECT
1410x8D保活超时 (Keep Alive timeout)DISCONNECT
1420x8E会话被接管 (Session taken over)DISCONNECT
1430x8F主题过滤器无效 (Topic Filter invalid)SUBACK, UNSUBACK, DISCONNECT
1440x90主题名无效 (Topic Name invalid)CONNACK, PUBACK, PUBREC, DISCONNECT
1450x91报文标识符在使用中 (Packet Identifier in use)PUBACK, PUBREC, SUBACK, UNSUBACK
1460x92没有发现报文标识符 (Packet Identifier not found)PUBREL, PUBCOMP
1470x93超出接收最大值 (Receive Maximum exceeded)DISCONNECT
1480x94主题别名无效 (Topic Alias invalid)DISCONNECT
1490x95报文太大 (Packet too large)CONNACK, DISCONNECT
1500x96消息传输速率太高 (Message rate too high)DISCONNECT
1510x97超出限额 (Quota exceeded)CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT
1520x98管理行为 (Administrative action)DISCONNECT
1530x99有效载荷格式无效 (Payload format invalid)PUBACK, PUBREC, DISCONNECT
1540x9A不支持消息保留 (Retain not supported)CONNACK, DISCONNECT
1550x9B不支持的QoS (QoS not supported)CONNACK, DISCONNECT
1560x9C使用另一台服务器 (Use another server)CONNACK, DISCONNECT
1570x9D服务器被移除 (Server moved)CONNACK, DISCONNECT
1580x9E不支持的共享订阅 (Shared Subscription not supported)SUBACK, DISCONNECT
1590x9F超出连接速率 (Connection rate exceeded)CONNACK, DISCONNECT
1600xA0最大连接时间 (Maximum connect time)DISCONNECT
1610xA1不支持的订阅标识符 (Subscription Identifiers not supported)SUBACK, DISCONNECT
1620xA2不支持的通配符订阅 (Wildcard Subscription not supported)SUBACK, DISCONNECT

原因码是用来表明操作结果的一个单字节无符号值,小于 0x80 的原因码表明操作的结果是成功的,正常情况下,操作成功返回的原因码值为 0。 如果返回的原因码大于等于 0x80,就说明操作失败了。

CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, DISCONNECT 和 AUTH 控制报文的原因码存在可变报头中,而 SUBACK 和 UNSUBACK 报文在有效载荷中包含了一张原因码的列表。