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

HTTP-ошибки¶

Код	Причина	Повтор запроса
`400`	Ошибка модели, бизнес-правила или доступа к объекту	Только после исправления запроса или состояния объекта
`401`	Токен отсутствует, недействителен или истек	Обновить токен и повторить один раз
`403`	Роль пользователя не разрешает метод	Только после изменения прав
`404`	Неверный путь или ресурс не найден	Проверить базовый URL, регистр пути и ID
`429`	Превышена допустимая частота запросов	После `Retry-After` или с экспоненциальной задержкой
`5xx`	Временная серверная ошибка	Ограниченное число повторов с экспоненциальной задержкой и случайным сдвигом

Ответ 400 может содержать текст бизнес-ошибки. Сохраняйте тело ответа в техническом журнале без токенов и персональных данных.

Ограничения повторов¶

Не повторяйте изменяющий запрос после неопределенного результата вслепую. Сначала прочитайте объект и проверьте, была ли операция применена.
POST /api/Orders/Apply не следует считать идемпотентным только по externalId. После создания сохраните возвращенный ID CARGO.RUN.
При 401 обновите access token и повторите исходный запрос не более одного раза.
Для 429 учитывайте Retry-After, если заголовок присутствует.

Ограничения списков¶

Методы списков могут поддерживать $filter, $orderby, $top и $skip. Набор доступных полей зависит от модели конкретного метода. Используйте стабильную сортировку и не увеличивайте $skip, пока текущая страница не обработана успешно.

GPS и фактические данные¶

truckCurrentLocation = null не является ошибкой запроса.
Координаты считаются последними известными, а не гарантированно текущими; проверяйте fixedAt.
По завершенному заказу актуальная трансляция не продолжается, но последнее положение может оставаться в ответе.
Фактические даты точки могут быть null, пока соответствующее событие не зафиксировано.

Безопасность¶

Не помещайте пароль, access token, refresh token, паспортные данные и реальные телефоны в примеры, журналы или контекст ИИ-системы. Для диагностики используйте обезличенные значения.