ATI.SU API: ошибки 429 и 403, лимиты и повторные запросы
Интеграция с ATI.SU может неделями работать без заметных проблем, а затем начать получать ответы 429 или 403 во время массового обновления грузов. Частая реакция — немедленно повторить запрос. Если таких задач много, повторы образуют ещё одну волну нагрузки: очередь растёт, одинаковые операции конкурируют между собой, а суточный лимит расходуется быстрее. В результате временное ограничение превращается в длительный сбой обмена между ATI.SU, 1С и TMS.
Чтобы исправить такую ситуацию, сначала нужно определить вид ограничения. HTTP-код сам по себе важен, однако его недостаточно: следует сохранить безопасную часть ответа, адрес и тип операции, время, номер попытки и идентификатор локальной задачи. Полный токен доступа и персональные данные в журнал не записывают. После этого можно решить, стоит ли повторять запрос, когда именно это делать и требуется ли вмешательство сотрудника.
Чем ошибка 429 отличается от 403
В официальных требованиях ATI.SU для интеграций установлен общий предел: не более десяти запросов в секунду от одного контакта. При превышении сервис возвращает 429. Документация рекомендует сначала подождать 100 миллисекунд, а при следующем таком ответе удваивать задержку. Это классический сценарий временного ограничения: запрос потенциально корректен, но его нужно отложить.
Код 403 нельзя автоматически трактовать как ещё один вариант перегрузки. Он может означать, что операция сейчас запрещена правилом самого метода. Официальный пример — обновление даты размещения конкретного груза: такой запрос разрешён не чаще одного раза в 60 минут. Если интервал ещё не прошёл, ATI.SU возвращает 403 с документированным кодом cargo_application_delay_not_ellapsed. Повтор каждую секунду не приблизит успешное выполнение. Задачу нужно перенести на допустимое время.
| Ответ | Что обычно проверять | Действие очереди |
|---|---|---|
| 429 | Частоту запросов одного контакта и параллельные процессы | Отложить, увеличить паузу, снизить параллельность |
| 403 с ограничением интервала | Время предыдущей операции и правило метода | Назначить ближайшее допустимое время |
| Иной 403 | Права контакта, условия метода и текст ответа | Остановить слепые повторы, передать на разбор |
Какие лимиты нужно учитывать в расчёте
Секундный предел — только один уровень. Для отдельных операций действуют суточные и интервальные ограничения. Официальные требования указывают до 5000 изменений данных грузов за 24 часа от одного контакта для запроса обновления груза. Создание грузов ограничено 500 операциями за 24 часа на контакт; для фирмы общий предел рассчитывается по числу контактов, имеющих доступ к API, умноженному на 500. Эти цифры нельзя превращать в план «использовать квоту до последнего запроса»: часть ёмкости нужна для ручных исправлений, повторов после сетевых ошибок и срочных операций.
Перед разработкой полезно посчитать пиковый поток. Если ночью требуется обновить 40 тысяч записей, важно понять, какие из них действительно изменились и какой метод нужен каждой группе. Полная повторная отправка неизменившихся данных расходует лимит без бизнес-результата. Обычно помогает журнал последней подтверждённой версии, сравнение значимых изменений и разделение очередей: создание, изменение, обновление даты, чтение статусов. У каждой группы будет собственная политика повтора.
Почему HTTP 200 ещё не гарантирует успех всех операций
Массовый запрос может завершиться HTTP 200, но вернуть ошибку для отдельных объектов. В правилах ATI.SU отдельно описан массовый подъём грузов: общий ответ способен быть успешным, при этом внутри результата у конкретных грузов будут указаны ограничения. Поэтому интеграция должна разбирать результат каждой позиции, а не помечать весь пакет выполненным по одному HTTP-коду.
Практическая модель состоит из двух уровней. Сначала сохраняется результат транспортного вызова: состоялся ли обмен и какой код вернул сервер. Затем фиксируется исход каждой бизнес-операции в пакете. Успешные позиции закрываются, временно ограниченные получают новое время выполнения, постоянные ошибки уходят в отдельный список. Повтор всего пакета создаёт лишнюю нагрузку и может повторно обработать уже успешные записи.
Как устроить безопасную очередь повторов
Очередь должна ограничивать скорость централизованно. Если сайт, 1С, фоновый обработчик и ручной скрипт обращаются к ATI.SU независимо, каждый процесс видит только собственные десять запросов, а общий предел контакта превышается. Единый диспетчер либо общий счётчик дают процессам одно представление о доступной пропускной способности.
- Назначьте локальный идентификатор операции. Он связывает бизнес-объект, тип действия и версию данных, но не заменяет идентификаторы ATI.SU.
- Ограничьте число одновременных запросов. Запас ниже документированного предела защищает от соседних процессов и неточного распределения по времени.
- Для 429 применяйте нарастающую паузу. Начните с указанной ATI.SU задержки и удваивайте её при повторных ограничениях; добавьте небольшое случайное смещение, чтобы работники не проснулись одновременно.
- Для интервального 403 рассчитывайте время допуска. Такая задача ждёт нужного момента, а не участвует в частом цикле повторов.
- Ограничьте количество попыток. После заданного числа или предельного возраста задача попадает в разбор, сохраняя последнюю понятную причину.
- Перед повторной записью проверяйте результат. Сетевой обрыв мог произойти после того, как удалённая система приняла операцию. Если API позволяет получить состояние, сначала выполняют безопасную проверку.
Повторяемость операции проектируют по её смыслу. Чтение состояния обычно можно повторить без изменения данных. Создание и изменение требуют проверки на уже выполненное действие и устойчивого сопоставления локального объекта с объектом ATI.SU. Универсальная кнопка «повторить всё» для таких сценариев опасна.
Как не исчерпать суточную квоту ночью
В очереди нужен отдельный бюджет на сутки. Он показывает выполненные операции по контакту и методу, прогноз до конца окна и резерв. При приближении к пределу второстепенные обновления переносятся, а критичные сохраняют место. Одновременно полезно исключить дубли: одинаковые ожидающие изменения одного объекта можно объединить, оставив последнюю актуальную версию.
Суточный график помогает увидеть причину. Резкий пик после регламентного задания указывает на пакетную выгрузку; ровный высокий поток — на слишком частый опрос или обновление без проверки изменений; ступень повторов — на неверную реакцию на ошибку. Простого счётчика 429 недостаточно: важно видеть исходные и повторные запросы отдельно.
Как тестировать, если API работает с реальными данными
ATI.SU предупреждает, что тестовые обращения к API выполняются в рабочей среде. Для публикации грузов документация предлагает использовать персональную Площадку: такие записи будут доступны только участникам выбранной площадки. Даже при этом тестовые данные маркируют и удаляют по согласованному сценарию. Разработчик не должен массово создавать записи, предполагая наличие отдельной песочницы.
Набор проверок включает единичное создание или изменение, повтор того же задания после искусственного сетевого сбоя, получение 429 на контролируемой нагрузке без выхода за допустимые рамки, ожидание интервального ограничения и разбор частичной ошибки пакета. Отдельно проверяют перезапуск обработчика: ожидающие задачи должны продолжиться без потери и без новой отправки уже завершённых операций.
Что контролировать после запуска
- число исходных запросов, повторов, 429 и 403 по типу операции;
- возраст самой старой задачи и размер каждой очереди;
- долю пакетов с частичными ошибками;
- расход суточного бюджета и прогноз до окончания окна;
- количество задач, которые требуют ручного решения;
- расхождение между локальным состоянием и подтверждённым результатом ATI.SU.
Оповещение лучше строить не по единичному ответу, а по влиянию на процесс. Один 429, после которого очередь быстро восстановилась, не требует ночного звонка. Рост возраста задач, исчерпание суточной квоты или повторяющийся 403 неизвестного типа уже означают, что обмен не укладывается в рабочий срок.
Если интеграция уже перегружает API, сначала останавливают неконтролируемые повторы, сохраняют очередь и оценивают фактическое состояние объектов. Затем вводят лимитер и правила для каждого класса ошибок. Такой порядок снижает риск дублей и позволяет вернуть обмен без массовой повторной отправки.