Начало работы
Ошибки и лимиты
Отказ приходит двумя способами: HTTP-кодом на уровне транспорта и объектом result.info на уровне приложения.
Ошибки уровня приложения
Приходят с кодом 200: запрос корректен, но результата нет.
Проверять только HTTP-статус недостаточно. Если в ответе есть result.info, показывайте пользователю его title и text: сервер уже вернул их на нужном языке.
| Поле result.info | Тип | Обязательный | Описание |
|---|---|---|---|
type | enum | да | Тип сообщения: default, info, success или error. Отказ приходит как error, но отсутствие данных — например «Vin не найден» — приходит с типом info. |
title | string | нет | Заголовок сообщения, готовый к показу пользователю. |
text | string | нет | Текст сообщения на языке из заголовка Accept-Language. |
html | string | нет | Оформленный вариант текста, если сервер его прислал. |
links | object[] | нет | Ссылки для продолжения работы: { q, title }. Указатель q передаётся в /api/q. |
200 OK
{
"success": true,
"result": {
"info": {
"type": "info",
"title": "Информация",
"text": "Vin не найден"
}
}
}HTTP-коды ответов
| HTTP | Код ошибки | Когда возникает |
|---|---|---|
| 200 | result | Запрос выполнен, полезная нагрузка в поле result. |
| 200 | result.info | Логический отказ: запрос принят, но данных нет. Причина — в result.info, профильные поля (vehicle, lists, node) при этом отсутствуют. |
| 401 | Unauthorized | Заголовок Authorization не передан, access_token истёк или повреждён. Нужно обновить пару через /auth/refresh и повторить запрос. |
| 401 | Unauthorized | Ответ /auth/refresh: refresh_token истёк или отозван. Нужно заново пройти вход через /auth/login-token. |
| 429 | Too Many Requests | Превышен лимит частоты запросов. Запрос не выполнен — повторите его позже, снизив темп. |
У ответов с кодом 4xx и 5xx тело одинаковое — без обёртки result:
| Поле тела ошибки | Тип | Обязательный | Описание |
|---|---|---|---|
statusCode | number | да | HTTP-код ответа, дублирует статус. |
timestamp | string | да | Момент отказа в формате ISO 8601. |
path | string | да | Путь запроса без базового адреса. |
method | string | да | HTTP-метод запроса. |
message | string | да | Причина отказа, например Unauthorized. |
401 Unauthorized
{
"statusCode": 401,
"timestamp": "2026-09-01T11:19:15.591Z",
"path": "/api/vin",
"method": "GET",
"message": "Unauthorized"
}Машиночитаемые коды в разработке
Поле message содержит текст статуса, а не код ошибки приложения. Отдельные машиночитаемые коды будут добавлены, когда их зафиксирует API.
Повторные попытки
Единственный сценарий повтора, который сейчас реализован на клиенте.
- Запрос к
/api/*вернул 401. - Клиент запрашивает новую пару токенов методом
/auth/refresh. - Исходный запрос повторяется один раз с новым
access_token. - Если и рефреш ответил ошибкой — выполняется повторный вход через
/auth/login-token.
Повторяйте запрос один раз
Обновление токена и повтор запроса выполняются однократно: бесконечный цикл повторов при неверных id и token только создаст лишнюю нагрузку.
Лимиты запросов
Частота запросов ограничена двумя окнами, они действуют одновременно.
- 20 запросов в минуту — короткое окно.
- 100 запросов за 10 минут — длинное окно.
Лимиты проверяются на каждый запрос к API. При превышении любого из окон сервер отвечает 429 Too Many Requests, запрос не выполняется. Остаток квоты запросов считайте на своей стороне.
Держите средний темп до 10 запросов в минуту
Минутное окно допускает короткие всплески до 20 запросов, но окно в 10 минут ограничивает средний темп: 100 запросов за 10 минут — это 10 запросов в минуту.