Лимит API — это ограничение поставщика на то, сколько раз в единицу времени ваша система имеет право к нему обратиться. При превышении сервис перестаёт отвечать по существу: сначала отказывает на отдельных запросах, потом замедляется, потом временно блокирует ваш ключ доступа. И у части поставщиков новые обращения во время блокировки продлевают её, поэтому обычная реакция «повторим ещё раз» делает хуже.
Про лимиты почти всегда узнают задним числом — после того, как обмен встал, остатки разъехались с площадкой и кто-то потратил день на переписку с поддержкой. Причина в том, что на демонстрации лимиты не видны: на десяти тестовых товарах в один магазин упирается только очень небрежный обмен. Упирается он на боевом каталоге, через две недели после запуска.
Дальше — четыре вида ограничений, четыре стадии превышения, арифметика проектирования обмена под лимит и пять вопросов, которые надо задать поставщику API до начала работ. Модель для всех расчётов одна: продавец с пятью магазинами на площадках, общий каталог 12 000 позиций, один ключ доступа, лимит 100 запросов в минуту.
Четыре вида ограничений
Ограничение «сто запросов в минуту» — только один из четырёх видов, и обычно не тот, который останавливает проект. Первичная загрузка чаще упирается в ограничение на объём выборки, а ночные выгрузки — в суточную квоту.
| Вид ограничения | Как выглядит | Типичный порядок величины | Что ломает в первую очередь |
|---|---|---|---|
| Частота запросов | Не больше N обращений в минуту или в секунду | от 10 до 300 в минуту на ключ | Поштучное обновление остатков и цен |
| Суточная квота | Не больше N обращений или заказанных отчётов в сутки | от нескольких сотен до десятков тысяч | Полные ночные выгрузки и повторный прогон после сбоя |
| Объём одной выборки | За один раз отдаётся не больше N записей или период не длиннее N дней | 100–1 000 записей, окно 30–90 дней | Первичная загрузка истории заказов и отчётов |
| Число параллельных операций | Одновременно выполняется не больше N задач по одному ключу | от 1 до 10 | Попытка ускориться, запустив обмен в несколько потоков |
Пятое ограничение формально лимитом не называется, но ведёт себя так же: часть операций у поставщика асинхронна. Вы отправляете задание, получаете ответ «принято» и обязаны потом отдельно спросить результат. Если обмен считает успехом слово «принято», расхождения начинаются на второй неделе — этот сюжет мы разбирали в материале про возможности и лимиты API маркетплейсов.
Что происходит при превышении: четыре стадии
Превышение — не бинарное событие «работает или забанили». Обычно это лестница из четырёх ступеней, и на первых двух ещё можно всё исправить, если их видно в мониторинге.
- 1Отказ на отдельных запросах. Сервис отвечает явным признаком «слишком часто» и нередко указывает, через сколько секунд повторить. Это подарок: если обмен читает указание и ждёт ровно столько, дальше ничего не случается.
- 2Замедление. Ответы приходят, но медленнее обычного. Со стороны выглядит как «интернет тормозит», а на деле поставщик уже придерживает ваш поток. Ловится только сравнением времени ответа со вчерашним — это один из сигналов в мониторинге интеграций.
- 3Временная блокировка ключа. От нескольких минут до нескольких часов. В этот период обмен не идёт вообще, и это ровно тот случай, когда нужен буфер и план на час простоя из статьи про недоступный сервис.
- 4Продление окна блокировки. У части поставщиков каждое обращение во время ограничения перезапускает счётчик. Обмен, который «просто повторяет», может держать себя в бане часами при том, что исходное окно было пятиминутным.
Типичная авария выглядит так: обмен упёрся в ограничение, начал повторять неудачные запросы без паузы, очередь стала расти, каждая новая операция тоже пошла на площадку — и нагрузка на поставщика в момент вашего бана выросла в несколько раз. Правильная реакция обратная: остановиться, выдержать указанную паузу, пропустить одну пробную операцию и только потом возобновлять поток с ограничением скорости. Лестница повторов с нарастающими интервалами разобрана в материале про очередь и повторные попытки.
Арифметика: почему пакеты решают, а потоки нет
Самая частая ошибка проектирования — обновлять данные поштучно, по одному товару за запрос. На тестовом каталоге это незаметно, на боевом даёт вот такую арифметику.
Из этого следует второй, менее очевидный вывод: увеличить число потоков нельзя. Лимит считается на ключ, поэтому пять параллельных обменов расходуют тот же самый бюджет в пять раз быстрее и просто быстрее упираются в стену. Ускоряет только уменьшение числа запросов — пакеты, подписка на события вместо опроса и отказ от повторной передачи неизменившихся данных.
Третий приём — приоритет и распределение по времени. Не все данные нужны одинаково часто: остатки по трёмстам ходовым позициям важны каждые пятнадцать минут, а остальной каталог спокойно живёт с обновлением раз в два часа. Ниже — бюджет запросов спроектированного обмена для той же модели.
| Задача | Как считается | Запросов в сутки |
|---|---|---|
| Остатки ходовых 300 позиций, каждые 15 минут | 3 пакета × 5 магазинов × 96 раз | 1 440 |
| Полный круг остатков 12 000 позиций, каждые 2 часа | 120 пакетов × 5 магазинов × 12 раз | 7 200 |
| Опрос новых заказов, каждые 5 минут | 1 запрос × 5 магазинов × 288 раз | 1 440 |
| Цены, раз в сутки | 120 пакетов × 5 магазинов × 1 раз | 600 |
| Итого расход | сумма строк выше | 10 680 |
| Доступно при 100 запросах в минуту | 100 × 60 × 24 | 144 000 |
Обмен расходует 7,4 % суточного бюджета. Такой запас закладывается не из аккуратности: после любого сбоя нужно догнать пропущенное, а первичная загрузка истории заказов за квартал съедает разом больше, чем неделя обычной работы. Обмен, спроектированный впритык к лимиту, ломается на первом же восстановлении после простоя.
Почему число магазинов и размер каталога попадают в смету
Владельцы часто удивляются, что подрядчик спрашивает про количество кабинетов и объём каталога, когда речь идёт «про одну и ту же интеграцию». Причина прямая: лимит выдаётся на ключ, а расходуют его все магазины сразу. Пятый магазин не добавляет пятую часть работы — он забирает пятую часть общего окна и заставляет пересобрать расписание.
- Каждый новый магазин отнимает долю лимита. При пяти кабинетах на общем ключе каждому фактически достаётся 20 запросов в минуту. Именно поэтому обмен, спокойно работавший на двух магазинах, встаёт при подключении четвёртого — и это не деградация кода, а арифметика.
- Каталог задаёт размер пакета и частоту. 12 000 позиций и 500 позиций — разные проекты: во втором случае поштучное обновление вообще допустимо и экономит неделю разработки.
- Первичная загрузка считается отдельно. История заказов за год при выборке по 100 записей и окне 30 дней — это сотни запросов и несколько часов работы под присмотром. Эту строку в смете часто забывают, а она разовая и заметная.
- Запас на восстановление — часть проекта. Если после суточного простоя обмен физически не успевает догнать пропущенное за ночь, значит, архитектура выбрана неверно. Проверять это надо на бумаге до начала работ, а не после первого инцидента.
Цена лимита, о котором не спросили
Модельная ситуация: обмен спроектировали поштучно, на двух магазинах он работал. После подключения ещё трёх круг обновления остатков растянулся до десяти часов, площадка дважды блокировала ключ, а покупатели начали заказывать то, чего на складе уже нет. Считаем месяц до того, как обмен переделали. Маржа с заказа — 836 ₽, как в остальных расчётах журнала.
В расчёт намеренно не включены санкции самой площадки за отмены по вине продавца и просадка карточек в выдаче: их размер зависит от конкретных правил и меняется, но направление известно, и оно не в вашу пользу. И обратите внимание на состав суммы: 66 000 ₽ из 127 776 ₽ — это работа, которую пришлось бы сделать в любом случае, только заложенная сразу она обходится примерно вдвое дешевле, потому что не тянет за собой повторную приёмку.
Пять вопросов поставщику API до начала работ
Эти пять вопросов задаются не подрядчику, а поставщику API — площадке, банку, сервису доставки — либо ищутся в его документации для разработчиков. Ответы на них меняют архитектуру обмена, а не её детали, поэтому спрашивать надо до сметы.
- 1На что считается лимит: на ключ, на приложение, на магазин или на юридическое лицо? От этого зависит, делится ли окно между кабинетами и имеет ли смысл заводить отдельные ключи.
- 2Какие методы под какой лимит попадают и есть ли отдельные ограничения на отчёты? Часто «тяжёлые» методы вроде выгрузки отчётов живут по своим правилам, гораздо более жёстким, чем обычные операции.
- 3Что приходит в ответе при превышении и указывается ли в нём пауза? Если сервис говорит, через сколько повторить, обмен обязан это читать. Если не говорит, паузу приходится подбирать, и это отдельная работа.
- 4Продлевается ли окно ограничения при обращениях во время него? Ответ «да» означает, что предохранитель обязателен, а не желателен.
- 5Есть ли пакетные методы, на сколько позиций за раз, и есть ли подписка на события вместо опроса? Подписка убирает опрос целиком и обычно снижает расход запросов в десятки раз. Что такое подписка на события и чем она отличается от опроса, объясняли в статье про API и вебхуки простыми словами.
Когда о лимитах можно не думать
Не всякий обмен нужно проектировать под ограничения. Есть три случая, где вопрос лимитов действительно не стоит, и тратить на него бюджет проекта не надо.
- Небольшой объём и редкий обмен. Выгрузка раз в сутки на 500 записей укладывается в любой лимит с запасом. Здесь достаточно одной проверки на бумаге, а специальная архитектура — лишние деньги.
- Обе системы внутри компании. Если обмен идёт между вашей CRM и вашим учётом на вашем сервере, лимит устанавливаете вы сами. Ограничения там всё равно нужны, но по другой причине — чтобы обмен не мешал людям работать в рабочее время.
- Готовый сервис-посредник берёт лимиты на себя. Это законный вариант, но с честной оговоркой: ограничения не исчезли, они переехали в тариф посредника и называются «число операций в месяц». Проверять надо ровно так же — по своему объёму, а не по названию тарифа.
И общий принцип для всех трёх случаев: даже когда лимиты не мешают сегодня, полезно один раз посчитать бюджет запросов на бумаге и записать результат в требования к обмену. Это полчаса работы, которые дают ответ на вопрос «а что будет, когда магазинов станет вдвое больше» — а этот вопрос возникает почти всегда и обычно в самый неподходящий момент.
