errors.md

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

API использует информирование при помощи HTTP кодов ответов, которые приложение должно корректно обрабатывать.

Помимо кода ответа, в теле ответа выдаётся дополнительная информация, позволяющая разработчику понять причину ошибки.

Ошибки выдаются в формате:

{
    "errors": [
        {
            "type": "applicants",
            "value": "first_name"
        },
        {
            "type": "applicants",
            "value": "last_name"
        }
    ]
}

Ключ type присутствует в каждом объекте и содержит текстовый идентификатор класса ошибки. Ключ value опционален и конкретизирует данные об ошибке.

При отправке POST/PUT запросов, которые подразумевают отправку форм, в объекте ответа с ошибкой может присутствовать объект fields с человекочитаемой информацией об ошибке:

{
    "errors": [],
    "fields": {
        "first_name": [
          "First name or last name required"
        ]
    }
}

Системная ошибка

Если сервис не может обработать запрос, то в ответ придёт 500 Internal Server Error и поле type будет содержать server_error.

В редких случаях ошибки с 5xx кодами могут возвращаться с телом не содержащим валидный JSON. Приложение должно в таких случаях ориентироваться только на код ответа.

Общие ошибки запроса

Неверный User-Agent

Подробнее про заголовок User-Agent.

HTTP code	type	value	описание
400	bad_user_agent		заголовок User-Agent не передан

Ошибки авторизации

Подробнее про авторизацию.

Ошибки использования авторизации

Если совершается авторизованный запрос в API, а предоставленная авторизация не действительна, вернётся ошибка с type oauth и одним из перечисленных value:

HTTP code	type	value	описание
401	oauth	bad_authorization	токен авторизации не существует или не валидный
401	oauth	token_expired	время жизни access_token завершилось, необходимо выполнить обновление access_token
401	oauth	token_revoked	токен отозван пользователем, приложению необходимо запросить новую авторизацию