Common Failures
Use the HTTP status and response code to decide what to do. Do not branch on the wording in message.
| Symptom | Action |
|---|---|
AUTH_INVALID | Check clientId and clientSecret |
APP_DISABLED | Confirm the API Client and application are enabled |
AUTH_SCOPE_DENIED | Add the permission identified by data.requiredScope, then obtain a new access token |
AUTH_EXPIRED | Obtain a new access token and retry the failed read once |
data.devices is empty | Confirm the device belongs to the account and the API Client can access it |
RATE_LIMITED | Wait for Retry-After; do not retry immediately |
DEVICE_OFFLINE | Wait for reconnection or use the last synchronized state where the endpoint provides it |
| A command has no final result | Query it by command ID; do not blindly repeat an operation with side effects |
Record requestId when contacting support.