Error Overview

WebSocket errors are divided into two categories:

• reply.success=false: one request failed
• session.error: a connection-level or session-level error

Error Reply

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

Error Codes

Code	Scenario	Client Handling
INVALID_REQUEST	Invalid request message format	Correct the client request format
AUTH_REQUIRED	Missing authentication information	Check the ticket in the connection URL
AUTH_INVALID	Invalid ticket, token, or authentication information	Reconnect after obtaining a new access token or wsTicket
AUTH_EXPIRED	Access token has expired	Reconnect after obtaining a new access token
AUTH_SCOPE_DENIED	The current client does not have the required permission	Check the API client permission settings
DEVICE_NOT_FOUND	Device does not exist	Check deviceId
DEVICE_OFFLINE	The device is currently offline	Retry after the device comes online
COMMAND_REJECTED	The command format is valid but is rejected by business rules	Check the relay index and the device type definition
RATE_LIMITED	Requests or heartbeats are too frequent	Reduce the frequency and retry
INTERNAL_ERROR	The OpenAPI service failed while processing the request	Retry later and record troubleshooting details

Rules

• Clients must branch on error.code
• error.message is only for display, logs, and troubleshooting
• When reporting a WebSocket issue, provide the requestId, topic, API client ID, connection time, and sanitized client logs