WebSocket 错误

WebSocket 请求错误使用与成功回复相同的顶层结构。code 为错误码，message 为可读说明，data 提供可选的结构化修复信息。

json

{
  "type": "reply",
  "requestId": "req_relay_001",
  "code": "AUTH_SCOPE_DENIED",
  "message": "This operation requires the device:control permission. Update the API Client permissions in the Developer Console and obtain a new access token.",
  "data": {
    "requiredScope": "device:control"
  }
}

回复不包含 success、嵌套的 error 或重复的 topic。

处理规则

根据 code 做程序分支。
message 用于展示、日志和排障，不作为稳定枚举。
data.requiredScope 指明缺少的 API Client 权限。调整权限后应重新获取 access token 和 WebSocket ticket。
data.retryAfterSeconds 指明限流后的建议等待秒数。
同一个 requestId 只对应一个 reply。

常见错误

`code`	处理建议
`INVALID_REQUEST`	检查 topic、operation 和参数
`UNKNOWN_TOPIC`	使用当前文档列出的请求主题
`AUTH_INVALID`	重新获取 access token 和 ticket
`AUTH_SCOPE_DENIED`	增加 `requiredScope` 指定的权限后重新认证
`DEVICE_NOT_FOUND`	检查设备是否属于当前账号
`DEVICE_OFFLINE`	等待设备上线后重试
`DEVICE_BUSY`	等待当前设备操作完成后退避重试
`IDEMPOTENCY_CONFLICT`	为新的操作生成新的幂等键
`RATE_LIMITED`	等待 `retryAfterSeconds` 后重试
`COMMAND_REJECTED`	检查设备能力、参数和当前状态
`DEVICE_TIMEOUT` / `TIMEOUT`	按未确认成功处理
`GATEWAY_UNAVAILABLE`	稍后重试，并保留原幂等键
`INTERNAL_ERROR`	记录 `requestId` 并联系支持

连接建立前的 HTTP 错误仍使用 REST 响应格式。连接关闭原因参见会话错误。

WebSocket 错误 ​

处理规则 ​

常见错误 ​

WebSocket 错误

处理规则

常见错误