B. 错误码对照表

HTTP API 常见错误

现象	可能原因	解决方法
连接被拒绝	服务未启动 / 端口错误	检查服务器状态，确认端口
400 错误	JSON 格式错误	检查请求体是否为合法 JSON
401/403	用户名密码错误	核对 body 中的 username/password
404	静态文件不存在	检查 HTTP_SERVER 目录下文件
500	服务器内部错误	查看日志，检查数据库连接
请求无响应 / 操作未生效	用了 function 字段	操作名字段是 cmd，不是 function 或 action

HTTP API 响应中的 cmdreq

业务成功与否看响应体的 cmdreq 字段，不看 HTTP 状态码（业务失败时状态码通常仍是 200）。

cmdreq	含义	解决方法
ok	成功	—
error	通用失败	多为账号密码错误或必填字段缺失
user error	认证失败	核对 username/password
noMore	没有更多数据	分页到底或关键字无匹配，属正常结束条件
no id	缺少设备 ID	设备类接口（plc_data_read 等）必须带 id；或目标设备离线

MQTT 连接错误

现象	可能原因	解决方法
连接超时	端口不通 / 防火墙拦截	检查网络连通性，放行 1883
认证失败	用户名密码错误	确认使用主账号或有效子账号
Client ID 冲突	重复客户端标识	更换唯一的 Client ID
频繁断线	心跳间隔过长	缩短 KeepAlive 间隔
无法使用 TLS	服务器仅监听 1883	通过反向代理或 VPN 提供加密

Modbus TCP 错误

现象	可能原因	解决方法
无法连接	端口 502 未开放	检查防火墙和服务器状态
设备地址无效	Unit ID 不为 0x01	确保 SCADA 配置 Unit ID = 1
寄存器无数据	地址未配置映射	在 Modbus 配置面板添加映射
数据异常	字节序不匹配	核对编码设置（ABCD/CDAB）

FTP 连接错误

现象	可能原因	解决方法
无法连接	端口 21 未开放	检查防火墙和服务器状态
登录失败	用户名密码错误	确认使用系统账号
传输失败	端口 20 被阻止	放行 20/21；服务器不支持 PASV，只用 20 端口传输数据

---