Skip to main content

Errors and status codes

A successful response is returned with the 200 OK code and contains the requested data. Some methods — delete, event acknowledgement, sending a command — return an empty response body on success.

Error format​

On error the API returns JSON:

{
  "Status": "FAIL",
  "ErrorMessage": "Choose a shorter time interval"
}
  • Status — always FAIL for errors.
  • ErrorMessage — a text description of the cause. The wording is intended for the developer and the integration log and may change between system versions.
  • Args — an optional field listing clarifying values, for example the name of the entity that caused a conflict. It is not present in every error.

HTTP status codes​

  • 200 OK — the request has been performed.
  • 400 Bad Request — the request is malformed: a required field is not filled in, the permitted interval length is exceeded, or the file format is not supported.
  • 401 Unauthorized — an incorrect login or password when obtaining a token, or the token is absent, expired, or corrupted. See Token lifetime.
  • 403 Forbidden — the user has no rights to the action or the requested data, the account is disabled, or the user's company is blocked.
  • 404 Not Found — an entity with the specified identifier does not exist or is not available to the user under their access rights.
  • 409 Conflict — a data conflict: a duplicate name, IMEI, or key UID, or the deletion of an entity that is still referenced.
  • 422 Unprocessable Content — the operation cannot be performed in the current state of the data, for example deleting a company that still has users assigned to it.
  • 429 Too Many Requests — the request has been rejected by the rate limiter (empty body, see the next section), or the limit of concurrently executed history import jobs is exceeded (body with an error description).
  • 500 Internal Server Error — an internal server error.

Rate limiting​

The request rate of a single client is limited using a sliding-window algorithm. The default values are 20 requests per 60 seconds; they are defined in the server settings and may differ in a particular installation.

The limit applies to all methods, including obtaining a token, and applies to the client as a whole rather than to each method separately. Requests exceeding the limit are rejected with the 429 Too Many Requests code and an empty response body; the Retry-After header is not sent.