错误码与故障排查
2025/11/9大约 6 分钟
错误码与故障排查
设备端通用 code
设备通用 code 信息,用于表达云端下行推送时设备侧业务处理的返回结果。
| 错误码 | 消息 | 描述 |
|---|---|---|
| 200 | success | 请求成功。 |
| 400 | request error | 内部服务错误, 处理时发生内部错误 |
| 460 | request parameter error | 请求参数错误, 设备入参校验失败 |
| 429 | too many requests | 请求过于频繁,设备端处理不过来时可以使用 |
| 100000-110000 | 自定义的错误信息 | 从100000到110000的错误码用于设备自定义错误信息,和云端错误信息加以区分 |
平台错误码速查
物模型与属性:
| 码值 | 含义 |
|---|---|
| 5092 | 属性 identifier 在物模型中不存在 |
| 5159 | 属性 dataType 未定义 |
| 6308 | 属性值类型与物模型定义不符 |
| 6207 | payload 不是合法 JSON |
| 6208 | 缺少 params(仅写云端日志,回复仍为 200) |
| 2013000007 | 属性上报 params 为空 |
| 2013000008 | 事件上报 identifier 为空 |
| 2009000000 | 事件 identifier 不在物模型中 |
| 2013000010 / 11 / 12 / 13 / 14 / 15 / 16 | 后台设置属性为空 / 类型不符 / 日期错误 / struct 错误 / struct 为空 / array 错误 / text 错误 |
服务调用:
| 码值 | 含义 |
|---|---|
| 2011000001 | 设备离线,无法调用服务 |
| 2011000003 | 同步调用超时(10 秒)未收到设备回复 |
产品与设备:
| 码值 | 含义 |
|---|---|
| 2001000003 | 动态注册签名错误 |
| 2001000005 | 产品未开启动态注册 |
| 2002000000 | 产品不存在 |
| 2005000000 | 设备不存在 |
| 2005000001 | 设备名已存在 |
| 2005000004 | 批量新增超过上限(1000) |
| 2008000001 | 设备离线导致升级失败 |
设备侧遥测:
| 码值 | 含义 |
|---|---|
| 2013000000 | 经纬度格式/范围不匹配 |
| 2013000001 | 指定固件版本不存在 |
| 2013000002 | messageId 为空 |
| 2013000003 | timestamp 为空 |
| 2013000005 | rssi 为空 |
| 2013000006 | 位置数据为空或分隔错误 |
| 2012000000 | 自定义 Topic 未配置 |
影子错误码 400/401/402/403/404/405/406/408/409/410/500 见设备影子。
故障排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
CONNACK 5(not authorized) | 签名不符 | 用签名示例自测;检查十六进制是否大写、是否误用 Base64 |
| 同上 | clientId 缺 |、productKey/deviceName 含 . | 修正设备标识命名 |
| 同上 | clientId 的 pk.dn 与 username 的 dn&pk 不一致 | 重新生成 |
| 同上 | 设备启动状态为停用 | 后台启用 |
| 同上 | signmethod 写成大写或非法值 | 固定小写 hmacsha256 |
| 同上 | 用错密钥(productSecret 当 deviceSecret) | 动态注册才用 productSecret |
| 同上 | 时间戳用了秒 | 必须 13 位毫秒 |
| TLS 握手失败 | 未配置 CA / 端口错 | 用 mqtts + 9883,加载 CA 证书 |
| 反复掉线 | keepalive 过大或 NAT 超时、重复 clientId | 缩短 keepalive、确保 clientId 全局唯一 |
| 连上但后台显示离线 | Kafka 消费异常或消费者未启动 | 检查 mqtt-topic 消费组 lag 与消费者日志 |
| 收不到属性设置/服务调用 | 未订阅或订阅写错 | 按订阅清单订阅;注意 + 不跨层级 |
| 属性上报后台无数据 | identifier 不在物模型 / 类型不匹配 | 看云端日志 5092、6308;double/float 必须带小数点 |
| 属性收到 200 但数据没入库 | 200 只是接收确认 | 见报文公共字段说明,按云端日志逐属性排查 |
| 属性记录时间是 1970 | {value,time} 未带 time | 带上毫秒时间或改用简写值 |
| 同步服务调用超时 | 10 秒内未回复到同一 /ext/rrpc/{id}/… | 保证回同一 topic、QoS1、耗时 < 10 秒 |
| 影子返回 409 | version 未大于库内版本 | 递增本地版本或传 -1 |
| 影子收不到回复 | 未订阅 /shadow/get/{pk}/{dn} | 补订阅 |
| 收不到 OTA 指令 | 未订阅 /ota/device/upgrade/{pk}/{dn};module 不匹配;无进行中批次 | 检查订阅与固件模块名 |
firmware/get_reply 中 data 为空 | 该设备无可用的升级批次 | 属正常,无需重试 |
firmware/pull 无响应 | 遗留通道未接通 | 改用 thing/ota/firmware/get |
| 本地日志后台不可见 | payload 不是数组 | 按本地日志格式发送,params 必须为数组 |
已知限制与实现差异
以下条目基于平台当前代码实现整理,开发前请通读,避免踩坑:
- 必须设备自行订阅:平台自动订阅逻辑已停用,任何下行都依赖设备预先 SUBSCRIBE。
- 遗留下行通道不可用:
/{pk}/{dn}/firmware/upgrade、/{pk}/{dn}/firmware/pull/reply以及后台接口POST /admin-api/iot/device-info/device/publish仍写入早期 Mica 时代的 Redis 流,在当前 EMQX 架构下不会送达设备。后台调试下发请使用POST /admin-api/iot/device-info/publish(走 EMQX REST)。 - 批量/历史属性上报未实现:
/sys/{pk}/{dn}/thing/event/property/batch/post与history/post无有效处理,且会被事件分支按「事件」吞掉(identifier 解析为property/batch等),发送后不会入库。 - 影子能力子集:支持
get、update(reported)、清空desired(update 中 desired 传任意非空字符串)、delete(reported 逐键移除);不支持设备侧删除单个desired键;version:-1会把库内版本写成 -1。 - 影子版本号步长非 1:后台更新影子时库内 +1、下发报文里的版本又 +1,设备端请勿假设连续步长。
- geopoint 属性校验缺陷:类型校验函数在 geopoint 分支缺少返回,导致该类型上报恒定判定失败;请用 text 或 struct 承载坐标。诊断/位置类上报走独立通道,不受影响。
- 属性/事件回复不反映校验结果:
post_reply在建包时即为 200,逐属性错误只进云端日志,设备无法从回复感知失败;缺少params时回复同样为 200(6208 只入日志)。 - 属性设置不等待设备回复:后台立即返回「下发成功」,
set_reply目前无人等待。 - 异步服务调用无
method字段,同步调用才有;两者 payload 结构不同。 - 网关子设备协议未实现:
/{pk}/{dn}/child/…系列 Topic 不会被解析。 - 鉴权不做时间戳新鲜度校验:连接参数一旦泄露可长期复用,请使用 TLS 并加强设备端密钥保护。
- deviceName 全局唯一:跨产品重名会创建失败;命名建议加厂商前缀。
- 信号/位置 Topic 采用后缀匹配:
signal/report、location/upload可挂在任意层级下,务必约定规范前缀/{pk}/{dn}/…。 - 位置上报入库仅按 deviceName 更新:极端情况下同名跨产品设备会互相覆盖,因此全局唯一命名很重要。
- date 类型必须为字符串:传数字时间戳会抛类型转换异常,消息可能不被完整处理。
- 影子「清空全部 reported」不可用:
{ "method": "delete", "state": { "reported": "null" } }在删除分支中会先把reported强转为 JSON 对象,抛出类型转换异常并返回errorcode:500;只有逐键列出待删键的方式可用。 - OTA 固件查询回复无
signMethod字段:firmware/get_reply的data只含version/isDiff/module/files/extData;signMethod只出现在批量推送指令中。 - OTA 进度 100 不判定完成:
progress step=100只记录进度,批次成功与否以inform上报版本是否匹配目标版本为准。 - 本地日志上报不受后台开关门控:上报始终入库;后台「设备本地日志上报」开关只用于通过日志配置(
mode)向设备同步开/关状态,建议设备遵循该配置。