WebSocket Errors

WebSocket request errors use the same top-level reply structure as successful replies. code is the error code, message is human-readable context, and data contains optional structured recovery details.

{
  "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"
  }
}

Replies do not contain success, a nested error, or a repeated topic.

Handling Rules

• Branch on code.
• Use message for display, logging, and troubleshooting, not as a stable enum.
• data.requiredScope identifies the missing API Client permission. Obtain a new access token and WebSocket ticket after updating permissions.
• data.retryAfterSeconds provides the recommended rate-limit delay in seconds.
• One requestId receives one reply.

Common Errors

code	Recommended action
INVALID_REQUEST	Check the topic, operation, and parameters
UNKNOWN_TOPIC	Use a request topic listed in the current documentation
AUTH_INVALID	Obtain a new access token and ticket
AUTH_SCOPE_DENIED	Add the permission in requiredScope and authenticate again
DEVICE_NOT_FOUND	Verify that the device belongs to the account
DEVICE_OFFLINE	Retry after the device comes online
DEVICE_BUSY	Wait for the current device operation to finish, then retry with backoff
IDEMPOTENCY_CONFLICT	Generate a new idempotency key for a new operation
RATE_LIMITED	Wait for retryAfterSeconds before retrying
COMMAND_REJECTED	Check device capability, parameters, and current state
DEVICE_TIMEOUT / TIMEOUT	Treat the operation as not confirmed successful
GATEWAY_UNAVAILABLE	Retry later with the original idempotency key
INTERNAL_ERROR	Record requestId and contact support

HTTP errors before the connection is established still use the REST envelope. See Session Errors for connection closures.