Тема
Ошибки
Формат ошибки
Ошибка возвращается с HTTP-статусом и JSON-телом. Код бизнес-ошибки передаётся в поле message:
json
{
"statusCode": 404,
"error": "Not Found",
"message": "PARCEL_NOT_FOUND"
}| Поле | Описание |
|---|---|
statusCode | HTTP-статус |
error | Стандартное название HTTP-статуса |
message | Код бизнес-ошибки из каталога ниже или текстовое описание |
code | Есть у ошибок валидации (FST_ERR_VALIDATION) и превышения лимита (RATE_LIMIT_EXCEEDED) |
Иногда message содержит не код, а текст — например "Supplier not found" или "Postomat provider error". Такие случаи указаны на страницах эндпоинтов.
Ошибка валидации
400 с code: "FST_ERR_VALIDATION". В message через запятую перечислены все найденные ошибки:
json
{
"statusCode": 400,
"code": "FST_ERR_VALIDATION",
"error": "Bad Request",
"message": "weight is a required field, currency is a required field"
}Неизвестные поля тела и query-параметры не вызывают ошибку — они отбрасываются.
Авторизация
| HTTP | message | Когда |
|---|---|---|
403 | TOKEN_NOT_VALID | Интеграционный эндпоинт: нет API-ключа (x-api-token или Authorization: Bearer) |
401 | UNAUTHORIZED | Интеграционный эндпоинт: API-ключ не найден. Эндпоинт с JWT: токен недействителен или истёк |
401 | TOKEN_NOT_VALID | Эндпоинт с JWT: нет заголовка Authorization: Bearer ... |
403 | ONLY_FOR_ADMIN | Действие доступно только администратору компании |
403 | FORBIDDEN | Действие недоступно для типа вашей компании |
Подробнее — Авторизация.
Лимит запросов
Платформа ограничивает число запросов за интервал времени. При превышении лимита API отвечает 429:
json
{
"statusCode": 429,
"code": "RATE_LIMIT_EXCEEDED",
"error": "Too Many Requests",
"message": "Too Many Requests"
}В ответе есть заголовок Retry-After — через сколько секунд можно повторить запрос. Дождитесь этого времени и повторите запрос. Конкретные значения лимитов не публикуются; если вашей интеграции нужен большой поток запросов, обсудите его с менеджером InLog.
Постоматы через платформу
Ошибки сервиса постоматов в группе /api/v1/integrations/postomat возвращаются со статусом 502 и телом { "message": "..." }, где message — текст или код ошибки сервиса постоматов (например ORDER_NOT_FOUND).
Каталог кодов
Источник сверки — коды ошибок в коде платформы. В основной таблице — коды, которые возвращают эндпоинты, описанные на этом портале.
Код (message) | HTTP | Где встречается |
|---|---|---|
TOKEN_NOT_VALID | 401, 403 | Авторизация — см. выше |
UNAUTHORIZED | 400, 401 | Авторизация; POST /api/v1/auth/refresh — недействительный refresh-токен (400) |
ONLY_FOR_ADMIN | 403 | Управление API-ключами и вебхуками |
FORBIDDEN | 403 | Управление вебхуками: компания не логистическая |
USER_NOT_FOUND | 400, 404 | Вход и обновление токенов |
PASSWORD_NOT_CORRECT | 406 | Вход: неверный пароль |
RATE_LIMIT_EXCEEDED | 429 | Превышен лимит запросов (в поле code) |
NOT_FOUND | 404 | API-ключ или вебхук не найден |
NOT_ACCEPTABLE | 406 | Объект принадлежит другой компании; посылку в текущем статусе нельзя переадресовать |
WEBHOOK_TYPE_EXIST | 406 | Вебхук с такими type и subtype уже есть |
WEBHOOK_PAYLOAD_INVALID | 406 | Некорректный payloadTemplate |
PARCEL_NOT_FOUND | 404 | Посылка маркетплейса не найдена |
ORDER_NOT_FOUND | 404 | Заявка маркетплейса в постомат не найдена |
POSTOMAT_NOT_FOUND | 404 | Постомат не найден (создание и переадресация посылки маркетплейса) |
WAREHOUSE_NOT_FOUND | 404 | Пункт выдачи не найден (создание посылки маркетплейса) |
COMPANY_NOT_FOUND | 404 | Целевой пункт выдачи не найден (переадресация посылки маркетплейса) |
CODE_NOT_FOUND | 404 | Создание посылки маркетплейса: не удалось назначить код клиента |
TRACK_CODE_ALREADY_EXISTS | 409 | Создание посылки: трек-код уже занят |
Прочие коды платформы
Эти коды возвращают эндпоинты, не описанные подробно на портале (см. Прочие эндпоинты), и кабинеты платформы. HTTP-статус зависит от эндпоинта.
Код (message) | Значение |
|---|---|
BAD_REQUEST | Некорректный запрос |
IDEMPOTENCY_KEY_REQUIRED | Не передан ключ идемпотентности |
CLIENT_NOT_FOUND | Клиент не найден |
MULTIPLE_CLIENTS_FOR_PHONE | Найдено несколько клиентов с этим телефоном |
DRIVER_NOT_FOUND | Водитель не найден |
CONTAINER_NOT_FOUND | Контейнер не найден |
TRUCK_NOT_FOUND | Грузовик не найден |
CARGO_NOT_FOUND | Груз не найден |
CAR_NOT_FOUND | Автомобиль не найден |
SPACE_NOT_FOUND | Место груза не найдено |
CARGO_SPACE_LAST | Нельзя удалить последнее место груза |
CURRENCY_CODE_EXISTS | Валюта с таким кодом уже есть |
CURRENCY_RATE_EXISTS | Курс валюты уже задан |
BATCH_NOT_FOUND | Партия не найдена |
BATCH_PENDING_SHIPMENT | Партия ожидает отправки |
TARIFF_NOT_FOUND | Тариф не найден |
RATE_NOT_FOUND | Ставка не найдена |
ROUTE_NOT_FOUND | Маршрут не найден |
EXPENSE_NOT_FOUND | Расход не найден |
ORDER_ALREADY_PAID | Заказ уже оплачен |
ORDER_ALREADY_CREATED | Заказ уже создан |
ORDER_CLAIM_CONFLICT | Конфликт при назначении заказа посылке, повторите запрос |
DELIVERY_WAREHOUSE_NOT_FOUND | Склад доставки не найден |
ORIGIN_WAREHOUSE_NOT_FOUND | Склад отправления не найден |
PARCELS_NOT_FOUND | Посылки не найдены |
STATUS_NOT_FOUND | Статус не найден |
INVALID_COMPANY | Недопустимая компания |
POSTOMAT_ID_REQUIRED | Не указан постомат |
POSTOMAT_SYSTEM_DOWN | Сервис постоматов недоступен |
NEWSLETTER_NOT_FOUND | Рассылка не найдена |
PDF_GENERATION_FAILED | Не удалось сформировать PDF |
CODE_NOT_VALID | Неверный код подтверждения |
CODE_EXPIRED | Срок действия кода подтверждения истёк |
PAY_FOR_ALL_PARCELS | Требуется оплатить все посылки |
Повторные запросы
| Ответ | Повторять? |
|---|---|
429 | Да — после паузы из Retry-After |
5xx, 502, сетевая ошибка на GET | Да — с экспоненциальной задержкой (например, 0,4 → 0,8 → 1,6 с, не больше 5 с) |
400, 401, 403, 404, 406, 409 | Нет — исправьте запрос |
Ошибка на создании (POST .../create) | Только с тем же Idempotency-Key там, где он поддерживается (посылки маркетплейса); в остальных случаях сначала проверьте, не создался ли объект |