Вaлидация. Статусы обработки запросов

VMS использует стандартные коды ответа HTTP для обозначения успешного ответа на запрос или запроса с ошибкой. В этом разделе документации разработчики могут найти описание стандартных кодов ответов HTTP, которые используются VMS API для информирования о статусе обработки запросов, и примеры валидации запроса с ошибкой.

Список HTTP кодов и их значения

При успешном завершении запроса сервер передает клиенту статус OK с кодом, находящимся в диапазоне 2xx.

В случае возникновения ошибки в процессе выполнения операции сервер передает сообщение, содержащее описание ошибки, а также соответствующий код из диапазонов 4хх и 5хх.

Коды в диапазоне 2xx	Указывают на успешное выполнение запроса.
200, 201, 204 – OK	Успешное выполнение запроса.
Коды в диапазоне 4xx	Указывают на ошибку запроса, который не удалось выполнить из-за ошибки в самом запросе, связанной с предоставленной информацией (например, пропущен обязательный параметр).
400 – Bad Request	Не удалось завершить запрос. Зачастую это связано с некорректной работой внешних систем. Запрос некорректный.
402 – Payment Required	Превышен лимит лицензий на создание камер или возникла другая проблема с лицензированием.
422 – Unprocessable Entity	Указанные в запросе данные неверны.
403 – Forbidden	Доступ к ресурсу запрещен. Детально в Управление доступом к API. Аутентификация.
404 – Not Found	Запрошенный ресурс не существует.
429 – Too Many Requests	Отправляется слишком много запросов к API за короткий промежуток времени.
Коды в диапазоне 5xx	Указывают на технические ошибки, встречаются редко. В основном, такие ошибки связанные с серверами VSaaS.
500, 502 – Server Errors	Редко. Ошибки на стороне сервера VSaaS.
503 – Service unavailable	Технические работы. Происходит обновление системы или устранение неполадок.

Валидация запроса с ошибкой

При обнаружении ошибки в процессе выполнения операции, сервер отправляет клиенту сообщение, содержащее детали этой ошибки, а также соответствующий HTTP-код состояния в диапазонах 400-499 (клиентские ошибки) или 500-599 (серверные ошибки).

В большинстве случаев API возвращает сообщение об ошибке в следующем формате. Однако API может возвращать ошибки и в других структурах в зависимости от запроса.

JSON

{
    "message": "Сообщение отсутствует",
    "errors": {
        "any_key": [
            "Детальная информация об ошибке"
        ]
    }
}

объект message – обычно представляет собой пустой объект и не содержит деталей ошибки. В некоторых случаях (например, при коде ошибки 400) это поле может включать описание ошибки.
объектerrors – предоставляет детальную информацию об ошибках, возникших при обработке запроса. Ключи в структуре errors указывают на поля запроса, вызвавшие ошибки. Важно отметить, что ошибки также могут возникать вне контекста конкретного поля. Объект errors может содержать несколько ошибок.

ПРИМЕР

Запрос содержит поле url со значением http//example.com. Для данного поля определено правило валидации, согласно которому оно должно представлять собой корректный URL-адрес и не превышать 10 символов в длину. Также в запросе присутствует поле date со значением 2000-01-01, которое должно соответствовать формату Y-m-d H:i:s.

Ответ на запрос с ошибкой будет выглядеть следующим образом:

CODE

{
    "message": "The given data was invalid",
    "errors": {
        "url": [
            "Поле url имеет ошибочный формат.",
            "Поле url не может быть более 10"
        ],
        "date": [
            "Поле date не соответствует формату Y-m-d H:i:s."
        ]
    }
}