Лимит API — это ограничение поставщика на то, сколько раз в единицу времени ваша система имеет право к нему обратиться. При превышении сервис перестаёт отвечать по существу: сначала отказывает на отдельных запросах, потом замедляется, потом временно блокирует ваш ключ доступа. И у части поставщиков новые обращения во время блокировки продлевают её, поэтому обычная реакция «повторим ещё раз» делает хуже.
Про лимиты почти всегда узнают задним числом — после того, как обмен встал, остатки разъехались с площадкой и кто-то потратил день на переписку с поддержкой. Причина в том, что на демонстрации лимиты не видны: на десяти тестовых товарах в один магазин упирается только очень небрежный обмен. Упирается он на боевом каталоге, через две недели после запуска.
Дальше — четыре вида ограничений, четыре стадии превышения, арифметика проектирования обмена под лимит и пять вопросов, которые надо задать поставщику API до начала работ. Модель для всех расчётов одна: продавец с пятью магазинами на площадках, общий каталог 12 000 позиций, один ключ доступа, лимит 100 запросов в минуту.
Четыре вида ограничений
Ограничение «сто запросов в минуту» — только один из четырёх видов, и обычно не тот, который останавливает проект. Первичная загрузка чаще упирается в ограничение на объём выборки, а ночные выгрузки — в суточную квоту.
| Вид ограничения | Как выглядит | Типичный порядок величины | Что ломает в первую очередь |
|---|---|---|---|
| Частота запросов | Не больше N обращений в минуту или в секунду | от 10 до 300 в минуту на ключ | Поштучное обновление остатков и цен |
| Суточная квота | Не больше N обращений или заказанных отчётов в сутки | от нескольких сотен до десятков тысяч | Полные ночные выгрузки и повторный прогон после сбоя |
| Объём одной выборки | За один раз отдаётся не больше N записей или период не длиннее N дней | 100–1 000 записей, окно 30–90 дней | Первичная загрузка истории заказов и отчётов |
| Число параллельных операций | Одновременно выполняется не больше N задач по одному ключу | от 1 до 10 | Попытка ускориться, запустив обмен в несколько потоков |
Пятое ограничение формально лимитом не называется, но ведёт себя так же: часть операций у поставщика асинхронна. Вы отправляете задание, получаете ответ «принято» и обязаны потом отдельно спросить результат. Если обмен считает успехом слово «принято», расхождения начинаются на второй неделе — этот сюжет мы разбирали в материале про возможности и лимиты API маркетплейсов.
Карта связей. Справа узел «API площадки» с рамкой-счётчиком «100 запросов в минуту на ключ». Слева пять узлов «Магазин 1» … «Магазин 5». В центре один узел «Ваше приложение, один ключ», через который проходят все линии. Сверху в приложение входят три подписанные задачи с частотой: «остатки ходовых 300 позиций — каждые 15 минут», «полный круг остатков 12 000 позиций — каждые 2 часа», «новые заказы — каждые 5 минут». На линии между приложением и API подпись «расход 10 680 запросов в сутки из 144 000». Чертёжный стиль, всё по-русски.
Что происходит при превышении: четыре стадии
Превышение — не бинарное событие «работает или забанили». Обычно это лестница из четырёх ступеней, и на первых двух ещё можно всё исправить, если их видно в мониторинге.
- 1Отказ на отдельных запросах. Сервис отвечает явным признаком «слишком часто» и нередко указывает, через сколько секунд повторить. Это подарок: если обмен читает указание и ждёт ровно столько, дальше ничего не случается.
- 2Замедление. Ответы приходят, но медленнее обычного. Со стороны выглядит как «интернет тормозит», а на деле поставщик уже придерживает ваш поток. Ловится только сравнением времени ответа со вчерашним — это один из сигналов в мониторинге интеграций.
- 3Временная блокировка ключа. От нескольких минут до нескольких часов. В этот период обмен не идёт вообще, и это ровно тот случай, когда нужен буфер и план на час простоя из статьи про недоступный сервис.
- 4Продление окна блокировки. У части поставщиков каждое обращение во время ограничения перезапускает счётчик. Обмен, который «просто повторяет», может держать себя в бане часами при том, что исходное окно было пятиминутным.
Типичная авария выглядит так: обмен упёрся в ограничение, начал повторять неудачные запросы без паузы, очередь стала расти, каждая новая операция тоже пошла на площадку — и нагрузка на поставщика в момент вашего бана выросла в несколько раз. Правильная реакция обратная: остановиться, выдержать указанную паузу, пропустить одну пробную операцию и только потом возобновлять поток с ограничением скорости. Лестница повторов с нарастающими интервалами разобрана в материале про очередь и повторные попытки.
Арифметика: почему пакеты решают, а потоки нет
Самая частая ошибка проектирования — обновлять данные поштучно, по одному товару за запрос. На тестовом каталоге это незаметно, на боевом даёт вот такую арифметику.
Из этого следует второй, менее очевидный вывод: увеличить число потоков нельзя. Лимит считается на ключ, поэтому пять параллельных обменов расходуют тот же самый бюджет в пять раз быстрее и просто быстрее упираются в стену. Ускоряет только уменьшение числа запросов — пакеты, подписка на события вместо опроса и отказ от повторной передачи неизменившихся данных.
Две горизонтальные полосы в минутах на общей оси. Верхняя, длинная, подписана «Поштучно: 60 000 запросов — 600 минут (10 часов)». Нижняя, очень короткая, подписана «Пакетами по 100: 600 запросов — 6 минут». Над обеими полосами общая рамка «Лимит 100 запросов в минуту на ключ». Справа выноска: «одни и те же 12 000 позиций × 5 магазинов». Ось подписана в минутах.
Третий приём — приоритет и распределение по времени. Не все данные нужны одинаково часто: остатки по трёмстам ходовым позициям важны каждые пятнадцать минут, а остальной каталог спокойно живёт с обновлением раз в два часа. Ниже — бюджет запросов спроектированного обмена для той же модели.
| Задача | Как считается | Запросов в сутки |
|---|---|---|
| Остатки ходовых 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 ₽ — это работа, которую пришлось бы сделать в любом случае, только заложенная сразу она обходится примерно вдвое дешевле, потому что не тянет за собой повторную приёмку.
Схема-лестница из четырёх ступеней слева направо и снизу вверх. Ступень 1 — «Отказ на отдельных запросах, сервис указывает паузу», подпись «видно в журнале». Ступень 2 — «Замедление ответов», подпись «видно только по сравнению со вчера». Ступень 3 — «Блокировка ключа, от минут до часов», подпись «обмен стоит». Ступень 4 — «Продление окна при новых обращениях», подпись «сами себя держим в бане». Вдоль лестницы сбоку стрелка вниз с подписью «правильная реакция: пауза, одна пробная операция, возобновление с ограничением скорости». Чертёжный стиль, всё по-русски.
Пять вопросов поставщику API до начала работ
Эти пять вопросов задаются не подрядчику, а поставщику API — площадке, банку, сервису доставки — либо ищутся в его документации для разработчиков. Ответы на них меняют архитектуру обмена, а не её детали, поэтому спрашивать надо до сметы.
- 1На что считается лимит: на ключ, на приложение, на магазин или на юридическое лицо? От этого зависит, делится ли окно между кабинетами и имеет ли смысл заводить отдельные ключи.
- 2Какие методы под какой лимит попадают и есть ли отдельные ограничения на отчёты? Часто «тяжёлые» методы вроде выгрузки отчётов живут по своим правилам, гораздо более жёстким, чем обычные операции.
- 3Что приходит в ответе при превышении и указывается ли в нём пауза? Если сервис говорит, через сколько повторить, обмен обязан это читать. Если не говорит, паузу приходится подбирать, и это отдельная работа.
- 4Продлевается ли окно ограничения при обращениях во время него? Ответ «да» означает, что предохранитель обязателен, а не желателен.
- 5Есть ли пакетные методы, на сколько позиций за раз, и есть ли подписка на события вместо опроса? Подписка убирает опрос целиком и обычно снижает расход запросов в десятки раз. Что такое подписка на события и чем она отличается от опроса, объясняли в статье про API и вебхуки простыми словами.
Когда о лимитах можно не думать
Не всякий обмен нужно проектировать под ограничения. Есть три случая, где вопрос лимитов действительно не стоит, и тратить на него бюджет проекта не надо.
- Небольшой объём и редкий обмен. Выгрузка раз в сутки на 500 записей укладывается в любой лимит с запасом. Здесь достаточно одной проверки на бумаге, а специальная архитектура — лишние деньги.
- Обе системы внутри компании. Если обмен идёт между вашей CRM и вашим учётом на вашем сервере, лимит устанавливаете вы сами. Ограничения там всё равно нужны, но по другой причине — чтобы обмен не мешал людям работать в рабочее время.
- Готовый сервис-посредник берёт лимиты на себя. Это законный вариант, но с честной оговоркой: ограничения не исчезли, они переехали в тариф посредника и называются «число операций в месяц». Проверять надо ровно так же — по своему объёму, а не по названию тарифа.
И общий принцип для всех трёх случаев: даже когда лимиты не мешают сегодня, полезно один раз посчитать бюджет запросов на бумаге и записать результат в требования к обмену. Это полчаса работы, которые дают ответ на вопрос «а что будет, когда магазинов станет вдвое больше» — а этот вопрос возникает почти всегда и обычно в самый неподходящий момент.
