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 ignore, 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 a production firmware.

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
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.