Error handling

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 Code422
Example Message{ "error": "Invalid SN" }
DescriptionOne or more of the parameters passed to the command is invalid or the command cannot be executed at this stage.
Suggested handlingNone
Unprocessable Entity — Device already registered (registration)
Error Code422
Example Message{ "error": "Device already registered" }
DescriptionReturned 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. If the existing device is claimed by an organization, it 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, and unclaimed devices raise no flag. An unclaimed, unlicensed device with no child devices that has not been seen for 24 hours (or, if it never reported, was registered more than 24 hours ago) is not refused: it is deleted and recreated, and the registration returns 201 with a new id and access_key.
Suggested handlingDo not retry in a tight loop. Back off (for example, exponentially up to several minutes between attempts) and keep retrying registration. Repeat attempts within 10 minutes get 429 (below). Once an admin approves the replacement, the next registration succeeds and returns new credentials. See Replace Device. If the device hasn't been claimed by an organization yet, it is recreated on its first registration after 24 hours unseen; if it is licensed or has child devices, delete it with Delete Device or contact Xyte support.
Too Many Requests — registration retry block (registration)
Error Code429
Example Message{ "error": "Too many requests" }
DescriptionReturned by device registration for 10 minutes after a 422 Device already registered answer, or after an unclaimed device was recreated, to repeat attempts with the same identity on the same device model. The response carries Retry-After: 600. In bulk registration the affected entry returns {"error":"Too many requests"}. After a 422, approving the replacement or dismissing the re-registration alert (the Approval required badge) on the device lifts the block at once; closing the "Device is trying to re-register" incident alone does not. Child devices are never blocked; they keep getting 422.
Suggested handlingWait at least the Retry-After interval, then retry registration. See Register Device.
Not Found
Error Code404
Example Message{ "error": "Invalid SN" }
DescriptionResource not found.
Suggested handlingNone
Unauthorized
Error Code401
Example Message
DescriptionThe device authorization is no longer valid.
Suggested handlingThe 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 Code403
Example Message{ "error": "Only allowed to set: inuse/removed/error" }
DescriptionThe requested state change is not allowed.
Suggested handlingNone
Too Many Requests
Error Code429
DescriptionToo many requests sent to the server (rate limiting).
Suggested handlingPause the device communication with Xyte for a few seconds. For registration, see the registration retry block above and honor Retry-After.