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 — the token is absent, expired, or corrupted. See Token lifetime.
  • 403 Forbidden — an incorrect login or password when obtaining a token, or the absence of rights to the requested data.
  • 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 limit of concurrently executed history import jobs is exceeded.
  • 500 Internal Server Error — an internal server error.
  • 503 Service Unavailable — the request has been rejected by the rate limiter, see the next section.
note

Some access-rights checks return the 500 code with a message about insufficient rights instead of 403. If the ErrorMessage field mentions rights or permissions, the cause is the user's set of rights.

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 503 Service Unavailable code and an empty response body; the Retry-After header is not sent.