错误总览

WebSocket 错误分为两类：

• reply.success=false：某次请求处理失败
• session.error：连接或会话级错误

Error Reply

{
  "type": "reply",
  "requestId": "req_op_001",
  "topic": "device.operation.execute",
  "success": false,
  "error": {
    "code": "COMMAND_REJECTED",
    "message": "Command was rejected."
  }
}

错误码

Code	场景	客户端处理
INVALID_REQUEST	请求消息格式不合法	修正客户端请求格式
AUTH_REQUIRED	缺少认证信息	检查连接 URL 中的 ticket
AUTH_INVALID	ticket、token 或认证信息无效	重新获取 access token 或 wsTicket 后重连
AUTH_EXPIRED	access token 已过期	重新获取 access token 后重连
AUTH_SCOPE_DENIED	当前客户端没有访问所需权限	检查 API Client 权限配置
DEVICE_NOT_FOUND	设备不存在	检查 deviceId
DEVICE_OFFLINE	设备当前离线	等待设备上线后重试
COMMAND_REJECTED	命令格式合法，但业务上被拒绝	检查继电器序号和设备 Profile
RATE_LIMITED	请求或心跳过于频繁	降低频率后重试
INTERNAL_ERROR	OpenAPI 服务处理失败	稍后重试并记录排障信息

规则

• 客户端必须基于 error.code 做程序分支
• error.message 仅用于展示、日志和排障
• 反馈 WebSocket 问题时，请提供 requestId、topic、API client ID、连接时间和脱敏后的客户端日志