Ограничения и лимиты API RetailCRM

Любая интеграция рано или поздно встречается с ограничениями API: частотой запросов, размерами пакетов и глубиной выборок. Понимание лимитов заранее избавляет от кода 429 в бою и от гонок при массовой синхронизации — правильная стратегия закладывается на этапе проектирования.

Частота запросов и код 429

Главное ограничение — частота обращений к API. RetailCRM считает запросы по аккаунту, и при превышении порога возвращает HTTP 429 Too Many Requests. Порог измеряется числом запросов в секунду и зависит от тарифа и типа аккаунта.

Практические следствия:

• несколько параллельных воркеров, бьющих в один аккаунт, суммируют нагрузку и быстрее упираются в лимит;
• пиковые массовые операции (импорт базы) нужно растягивать во времени;
• получив 429, нельзя просто повторять запрос сразу — это усугубит ситуацию.

Заголовки контроля лимитов

Ответы API сопровождаются служебными заголовками, по которым можно отслеживать остаток лимита и адаптировать темп. Ориентируйтесь на них вместо жёстко зашитых пауз:

Хорошая интеграция читает эти заголовки после каждого ответа и снижает темп, когда Remaining приближается к нулю, не дожидаясь отказа. Заголовок Retry-After, если он есть, задаёт минимальную паузу перед повтором.

Размеры пакетов и тел запросов

Пакетные методы ограничены количеством объектов за вызов. Ориентиры, которых стоит придерживаться:

• /orders/upload, /customers/upload — до 50 объектов за запрос;
• обновление остатков и цен — десятки предложений за вызов;
• фильтры-массивы (например filter[ids][]) тоже не стоит раздувать до тысяч значений.

Превышение лимита пакета приведёт к ошибке валидации. Поэтому большие объёмы разбивают на партии: например, импорт 10 000 заказов — это 200 вызовов /orders/upload по 50 штук, распределённых во времени с учётом частоты.

Ограничения пагинации и глубины выборки

Списочные методы отдают максимум 100 записей на страницу (limit=100). Глубокая пагинация по page имеет два минуса: она нагружает базу и уязвима к смещению при параллельных изменениях данных.

Для полной и корректной выгрузки применяют курсорный обход:

1. запросить первую страницу, отсортированную по id;
2. взять максимальный id из ответа;
3. следующий запрос — с filter[sinceId], равным этому id;
4. повторять, пока приходят записи.

Стратегии устойчивости: бэкофф и очереди

Надёжная интеграция проектируется так, чтобы лимиты не роняли обмен, а лишь замедляли его. Базовый набор приёмов:

• Экспоненциальный бэкофф: при 429 и 5xx повторять с растущей паузой (например, 1, 2, 4, 8 секунд) и джиттером;
• Очередь и единый лимитер: все запросы к аккаунту проходят через один ограничитель скорости, а не через независимых воркеров;
• Приоритеты: критичные операции (создание заказа) обслуживаются раньше фоновых выгрузок;
• Идемпотентность: повтор после сбоя не должен создавать дубли — опора на externalId.

Такой конвейер переживает всплески нагрузки и деградации API без потери данных.

Мониторинг и диагностика

Лимиты нужно наблюдать, а не угадывать. Что стоит логировать и отслеживать:

• долю ответов 429 и 5xx от общего числа запросов;
• значения X-Rate-Limit-Remaining в пиковые часы;
• задержки обработки очереди и глубину отставания;
• количество повторов на операцию.

Рост доли 429 — сигнал, что пора распределять нагрузку по времени или пересматривать архитектуру обмена. Метрики также помогают отличить проблему на стороне API от собственных ошибок интеграции.

Итог

Ключевые ограничения API RetailCRM — частота запросов с кодом 429, размеры пакетов (до 50 объектов), лимит страницы в 100 записей и глубина пагинации. Устойчивость достигается чтением заголовков лимитов, экспоненциальным бэкоффом, единым лимитером и курсорным обходом через sinceId.

Мы проектируем высоконагруженные интеграции, которые уважают лимиты API: с очередями, приоритетами и мониторингом. Если обмен с RetailCRM должен работать при тысячах операций в час и не падать на пиках, поможем построить архитектуру, которая держит нагрузку.