Перейти к содержанию

Ошибки и ограничения

HTTP-ошибки

Код Причина Повтор
400 Неверные поля или бизнес-правило Только после исправления
401 Недействительный или истёкший токен Один раз обновить токен
403 Нет доступа к операции или организации Только после изменения прав
404 Заявка не существует или недоступна текущему партнёру Не повторять без проверки ID или изменения доступа
429 Слишком частые запросы После Retry-After или паузы
5xx Временная серверная ошибка Ограниченно, с exponential backoff и jitter

Синхронные бизнес-ошибки могут возвращаться как text/plain.

Иллюстративный пример ошибки валидации; конкретный текст зависит от нарушенного правила:

HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

Для заявки необходимо указать не менее двух точек маршрута.

Методы чтения возвращают одинаковый статус 404 Not Found, если заявка не существует или недоступна текущему интеграционному клиенту. По HTTP-статусу различить эти случаи нельзя.

Ошибки очереди

Уровень Поле Успех Ошибка Где читать причину
Постановка команды commands[].status Success Failed commands[].message
Задача целиком QueuedApiTaskGetResultsModel.status Completed Error message
Объект задачи objects[].status Success Error или VersionMismatch objects[].message
Доставка webhook callbackStatus Delivered Error lastError
Диагностика синхронизации QueuedApiTaskObjectStatusJson.type Info Warn или Error QueuedApiTaskObjectStatusJson.message

Эти уровни независимы. Completed означает, что обработка задачи закончена, но не гарантирует успех каждого элемента objects[]. Аналогично, callbackStatus=Delivered подтверждает только доставку webhook и ничего не говорит об успешности объектов.

VersionMismatch используется механизмом ReadConfirmation, который партнёрским интеграционным клиентам недоступен. В документированных командах Write, Read и ReadQuery партнёр не должен получать этот статус. Если он всё же появился, не подтверждайте локальную версию объекта, зарегистрируйте диагностическое событие и заново прочитайте актуальные данные.

Подтверждённые ограничения

Ограничение Значение
Получение токена Не чаще двух запросов за 30 секунд
Idempotency-Key Не более 100 символов, действует 24 часа
Точки заявки Минимум 2
Состав маршрута Хотя бы одна погрузка и одна выгрузка
planEnterDate Обязателен для каждой точки
Порядок точек Строгий хронологический после приведения к UTC
Адрес точки Обязательная непустая строка, даже если координаты переданы
Координаты точки Необязательны; если переданы — [долгота, широта], кроме [0, 0]; если отсутствуют — определяются по адресу
ИНН Обязателен; 10 цифр для организации или 12 для ИП
Автомобиль, водитель и груз Обязательны
Прицеп Необязателен; если передан, обязателен номер
Асинхронные типы Только Bid
Асинхронные действия Write, Read, ReadQuery
Фактический маршрут Только синхронный метод
Автоматический пакет подписки До 100 объектов в одной задаче по текущей конфигурации
Список без $filter Последние 30 дней для GetList и ReadQuery; любой непустой $filter отменяет окно по умолчанию
Ссылки на файлы Временные; файл нужно скачать сразу или повторно запросить данные для новой ссылки

Webhook

  • порядок не гарантируется;
  • возможны повторы;
  • несколько изменений одной заявки могут объединяться;
  • повторяются сеть, 408, 429, 5xx;
  • остальные 4xx не повторяются;
  • не более пяти попыток с интервалами 10, 20, 40 и 80 секунд перед повторными отправками;
  • после пяти последовательных неудачных доставок подписка приостанавливается;
  • во время приостановки проверочная доставка выполняется каждые 5 минут;
  • успешная доставка или Tasks/Ping возобновляет подписку;
  • отдельного публичного статуса приостановки нет, а накопившиеся изменения могут быть отброшены;
  • необходим периодический контрольный ReadQuery.

Неподдерживаемые операции

  • Delete через партнёрскую очередь;
  • ReadConfirmation;
  • асинхронная работа с Car, Trailer, Driver, Counterparty, DistributionBid;
  • фактический маршрут внутри IntegrationBidDetailsModel;
  • частичное обновление заявки.

Валидация новых полей заявки

Поле Правило Ошибка
counterparty.name Обязательно при переданном counterparty Не указано наименование контрагента.
counterparty.name Не более 256 символов Наименование контрагента не должно превышать 256 символов.
counterparty.inn Если передан — 10 или 12 цифр ИНН контрагента … некорректен: ожидается 10 или 12 цифр.
vehicleType Хотя бы одно из name, tonnage, volume Не указаны тип ТС, тоннаж или объем.
vehicleType.name Не более 128 символов Тип ТС не должен превышать 128 символов.
vehicleType.tonnage Если передан — больше 0 Грузоподъемность должна быть больше 0.
vehicleType.volume Если передан — больше 0 Объем должен быть больше 0.
temperatureRegime Обязательны minimum и maximum Не указаны минимальная и максимальная температура.
temperatureRegime.* Каждая граница от −30 до 30 °C включительно Температура должна быть в диапазоне от -30 до 30 °C.
temperatureRegime minimum < maximum Минимальная температура должна быть меньше максимальной.
bidPoints[].geozone.address Обязательная непустая строка Не указан адрес точки N.
Геокодирование По адресу должна определиться точка Не удалось определить координаты точки N по адресу «…».