Overview
When the server encounters an error processing any HTTPs API calls, an HTTP error code is returned in the response and a detailed JSON object is returned (for some API calls and statuses).
Some commands have special error codes and messages, documented in the API Endpoints reference for each command. Below are generic errors that can be returned by all API calls.
Handling the errors is dependent on the device implementation and requirements. The error table specifies which can be ignored, which should be retried, and which require more complex handling.
Errors with the "None" handling correspond with errors that should be detected only during the development phase and should not happen in production firmware.
Other errors
Low-level Infrastructure and component errors might cause the returned data to be in HTML or other formats. Any errors with status code 50X (Starting with 5) should be carefully parsed to handle non-JSON body.
Common errors
| Unprocessable Entity | |
| Error Code | 422 |
| Example Message | { "error": "Invalid SN" } |
| Description | One or more of the parameters passed to the command is invalid or the command cannot be executed at this stage. |
| Suggested handling | None |
| Unprocessable Entity — Device already registered (registration) | |
| Error Code | 422 |
| Example Message | { "error": "Device already registered" } |
| Description | Returned by device registration when a device with the same identity (cloud ID, or MAC address and serial number, depending on the model's authentication method) is already registered. This typically happens after a factory reset wiped the device's UUID and Access Token. The existing device is flagged in the Organization portal with an Approval required badge, and an organization admin must approve the replacement there (or dismiss it). Child devices cannot be replaced this way. |
| Suggested handling | Do not retry in a tight loop. Back off (for example, exponentially up to several minutes between attempts) and keep retrying registration. Once an admin approves the replacement, the next registration succeeds and returns new credentials. If the device hasn't been claimed by an organization yet, contact Xyte support. |
| Not Found | |
| Error Code | 404 |
| Example Message | { "error": "Invalid SN" } |
| Description | Resource not found. |
| Suggested handling | None |
| Unauthorized | |
| Error Code | 401 |
| Example Message | |
| Description | The device authorization is no longer valid. |
| Suggested handling | The device's UUID and Access Token should be removed from storage and the device should attempt to re-register with the provisioning server. |
| Forbidden | |
| Error Code | 403 |
| Example Message | { "error": "Only allowed to set: inuse/removed/error" } |
| Description | The requested state change is not allowed. |
| Suggested handling | None |
| Too Many Requests | |
| Error Code | 429 |
| Description | Too many requests sent to the server (rate limiting). |
| Suggested handling | Pause the device communication with Xyte for a few seconds. |