Перейти к основному содержимому

Ошибки и коды ответов

Успешный ответ возвращается с кодом 200 OK и содержит запрошенные данные. Часть методов — удаление, квитирование событий, отправка команды — при успешном выполнении возвращает пустое тело ответа.

Формат ошибки​

При ошибке API возвращает JSON:

{
  "Status": "FAIL",
  "ErrorMessage": "Choose a shorter time interval"
}
  • Status — для ошибок всегда FAIL.
  • ErrorMessage — текстовое описание причины. Формулировки предназначены для разработчика и журнала интеграции и могут изменяться между версиями Системы.
  • Args — необязательное поле со списком уточняющих значений, например с наименованием сущности, вызвавшей конфликт. Присутствует не во всех ошибках.

Коды состояния HTTP​

  • 200 OK — запрос выполнен.
  • 400 Bad Request — запрос составлен некорректно: не заполнено обязательное поле, превышена допустимая длительность интервала, передан файл неподдерживаемого формата.
  • 401 Unauthorized — токен отсутствует, истёк или повреждён. См. Срок действия токена.
  • 403 Forbidden — неверные логин или пароль при получении токена либо отсутствие прав на запрошенные данные.
  • 404 Not Found — сущность с указанным идентификатором не существует или недоступна пользователю по правам доступа.
  • 409 Conflict — конфликт данных: дубликат наименования, IMEI или UID ключа, удаление сущности, на которую есть ссылки.
  • 422 Unprocessable Content — операция невыполнима в текущем состоянии данных, например удаление компании, за которой закреплены пользователи.
  • 429 Too Many Requests — превышен лимит одновременно выполняемых задач импорта истории.
  • 500 Internal Server Error — внутренняя ошибка сервера.
  • 503 Service Unavailable — запрос отклонён ограничителем частоты, см. следующий раздел.
примечание

Часть проверок прав доступа возвращает код 500 с сообщением о недостатке прав вместо 403. Если в поле ErrorMessage упоминаются права или разрешения, причиной является состав прав пользователя.

Ограничение частоты запросов​

Частота обращений одного клиента ограничивается по алгоритму скользящего окна. Значения по умолчанию — 20 запросов за 60 секунд; они задаются в настройках сервера и на конкретной установке могут отличаться.

Ограничение распространяется на все методы, включая получение токена, и действует на клиента целиком, а не на каждый метод в отдельности. Запросы сверх лимита отклоняются с кодом 503 Service Unavailable и пустым телом ответа; заголовок Retry-After не передаётся.