Лимиты API и управление квотами

Последний рабочий день месяца, 17.20. Бухгалтер сверяет заказы перед закрытием и обнаруживает, что за двое суток в CRM не попало ни одного. Команда, собиравшая интеграцию, отвечает коротко: система нас ограничивает. На деле произошло вот что. Утром кто-то попытался выгрузить тридцать тысяч записей для отчёта, синхронизация с маркетплейсом в те же часы продолжала тянуть заказы, поставщик засчитал и то и другое в один лимит и на несколько часов притормозил аккаунт. Заказы не потерялись, но двое суток их никто не видел: склад дважды собрал два заказа вручную, а одному клиенту дважды ушёл один и тот же счёт.

В большинстве компаний лимиты API становятся темой только после такого дня и приходят вместе с неверным вопросом: как нам поднять лимит? В этой статье разбираем, чем лимит скорости отличается от квоты, какой тип ограничения бьёт по вам и с каким симптомом, как правильно вести себя у стены, как выстраивать очереди и приоритеты, какие приёмы действительно снижают число запросов, как планировать квоту как общий ресурс, какой мониторинг предупреждает заранее, о чём спрашивать поставщика, где заканчивается совет «делайте всё в реальном времени» и как защитить данные при обрыве передачи.

Безопасная полосаПростойСтена лимита

Лимит скорости и квота — не одно и то же

Лимит скорости — это спидометр: он говорит, сколько запросов помещается в заданное окно времени. Квота — это указатель топлива: она ограничивает общий расход за сутки, месяц или период договора. Работают они независимо и друг друга не выручают. Суточной квоты может быть с запасом, но поминутный лимит остановит вас на полуслове; или вы идёте ровно и медленно, а квота заканчивается двадцатого числа, и оставшиеся десять дней синхронизации нет.

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

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

Какой тип ограничения бьёт по вам и как это выглядит

Когда интеграция встала, первое дело — понять, в какую именно стену вы упёрлись: симптом обычно прячет причину. В таблице ниже собраны типы ограничений, которые встречаются чаще всего, и то, как они проявляются со стороны операций.

Тип ограничения	Что ограничивает	Типичный симптом
Оконный лимит скорости	Запросы в секунду или минуту	Массовая задача встаёт на первых секундах
Суточная квота	Общее число вызовов за сутки	Синхронизация тихо смолкает под вечер
Параллельность	Число одновременно открытых запросов	Параллельные задачи блокируют друг друга
Весовая стоимость	Цена вызова, объём возвращаемых данных	Лимит выбирается очень малым числом вызовов
Доля на эндпоинт	Отдельный запас одного метода	Выгрузка отчёта душит синхронизацию заказов
Доля на пользователя	Норма на одну учётную запись	Задача одного человека тормозит всю команду

Самый обманчивый тип здесь — весовая стоимость. Если число вызовов невелико, а вы всё равно упираетесь в лимит, скорее всего вы запрашиваете больше данных, чем используете: запрос, возвращающий пятьсот записей, в учёте поставщика может стоить как пятьсот мелких вызовов. В многоканальных потоках заказов это встречается постоянно; логику такой синхронизации мы подробно описываем в материале об интеграции с маркетплейсами.

Как вести себя у стены

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

Правильное поведение — ступенчатое отступление: короткая пауза после первой неудачи и всё более длинные после следующих. Добавить немного случайности тоже обязательно, иначе сто задач, остановившихся одновременно, одновременно и повторятся, и стена вырастет снова. Если в ответе указано, сколько ждать, следуйте этому числу, а не догадкам.

Качество интеграции измеряется не тем, как быстро она работает без ограничений, а тем, насколько тихо она восстанавливается, упёршись в них.

Срочность запросов неодинакова

Самый редко обсуждаемый способ удержаться под лимитом — расставить приоритеты. Когда клиент заполняет форму на сайте, запись должна попасть в CRM за секунды. Выгрузка месячного отчёта, идущая в тот же момент, может опоздать на полчаса, и этого никто не заметит. Если обе стоят в одной очереди в порядке поступления, узкую пропускную способность съедает отчёт, а клиент ждёт.

Рабочая схема использует три очереди: события, которым нужен реальный масштаб времени; синхронизации, которым достаточно закрыться в течение дня; массовые задачи, которые подождут ночного окна. Каждой очереди задают свой потолок скорости так, чтобы сумма оставалась ниже лимита поставщика. Тогда напряжённый день замедляет самый эластичный поток, а не самый критичный. Когда стоит брать промежуточный слой с готовой логикой очередей и повторов, мы сравниваем в материале об интеграционных платформах.

Приёмы, которые реально снижают число запросов

Управление лимитами по большей части состоит не в том, чтобы лучше ждать, а в том, чтобы не отправлять вовсе. Семь приёмов ниже заметно снижают расход в большинстве внедрений, и ни один из них не требует разрешения поставщика.

• События вместо опроса: вместо вопроса каждые пять минут, не появился ли новый заказ, попросите вторую сторону сообщать о его создании; так исчезает почти весь холостой трафик.
• Дельта-синхронизация: тяните не все записи, а изменившиеся с прошлого запуска; достаточно, чтобы вторая система умела фильтровать по времени изменения.
• Пакетные методы: отправляйте сто записей одним вызовом, а не сотней; большинство поставщиков считает пакет за один запрос, а там, где действует вес, выигрыш всё равно остаётся.
• Сужение полей: запрашивайте только те поля, которыми пользуетесь; ответ становится меньше, а в системах с весовой оценкой падает и расход.
• Кэш: списки стран, категории товаров, ставки налога меняются редко; обновлять их раз в сутки достаточно.
• Склейка записей: сводите подряд идущие правки одной записи в одно обновление, чтобы пять исправленных в форме полей не превращались в пять вызовов.
• Сдвиг окна: переносите несрочные массовые задачи на часы, когда трафик заказов падает; та же работа укладывается в ту же квоту, никому не мешая.

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

Планируйте квоту как общий ресурс

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

Планирование начинается с простой таблицы: обычный суточный расход, расход в пиковый день и допустимая задержка для каждой интеграции. Записанные три числа обычно и есть первый момент, когда команда вообще видит свою квоту. Дальше решения даются легко: какой поток приоритетен, какой уходит в ночь, а какой оказывается лишним.

Опасны не будни, а разовые работы

Большинство инцидентов с лимитами рождается не из обычной работы. Первая миграция данных, массовое обновление десятков тысяч записей, дозагрузка истории под новый отчёт, зациклившийся сценарий автоматизации — всё это разовые задачи, и любая из них способна выбрать квоту за день. Поэтому мощность планируют по самому напряжённому дню, а не по среднему. Как разбивать массовые переносы на части и в каком порядке их запускать, мы разбираем в материале об импорте и экспорте данных.

Как узнать о проблеме до стены

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

Смотреть стоит на три вещи. Первая — число ошибок превышения и то, на каком методе они скапливаются. Вторая — глубина очереди: если она растёт в течение дня, мощность больше не покрывает спрос. Третья — отставание синхронизации, то есть время между событием и его появлением во второй системе. Как настроить оповещение, при котором об обрыве вы узнаёте раньше клиентов, читайте в материале о мониторинге интеграций.

О чём спрашивать поставщика

Выбирая интеграцию, об условиях по лимитам спрашивать не менее важно, чем о коммерческих, и именно это чаще всего пропускают. В документации ищите четыре пункта: на каком уровне применяются ограничения, на какой срок закрывается доступ при превышении, указывает ли ответ время ожидания и есть ли отдельный путь для массовых операций.

Есть и пятый вопрос, который задают редко: как сообщают об изменении лимитов? Поставщики со временем их ужесточают, и ужесточение без предупреждения останавливает интеграцию, работавшую вчера. Та же хрупкость возникает при смене версий, и защита от неё во многом общая; эту тему мы разбираем отдельно в материале об изменениях версий API.

Всё ли должно происходить в реальном времени?

Распространённый совет звучит однонаправленно: чем быстрее движутся данные, тем лучше. На практике граница этого совета наступает рано. Потоков, которым действительно нужны секунды, в компании немного: входящая заявка, подтверждение оплаты, списание со склада. Для всего остального пятнадцатиминутная задержка — разница, которую никто не заметит, и она снимает большую часть проблемы с лимитами в корне.

Верно и обратное, и это упускают: в некоторых потоках важна не задержка, а порядок. Если обновление заказа приходит раньше самого заказа, скорость вам ничего не дала. У готовых платформ автоматизации свой аналог лимита — квота операций; чем в этом отношении различаются два популярных подхода, мы разбираем в материале о сравнении платформ автоматизации.

Как защитить данные при обрыве

Самое дорогое последствие прерванной лимитом передачи — не задержка, а дубль. Запрос ушёл, поставщик его обработал, а ответ вернулся ошибкой превышения; интеграция считает это неудачей, отправляет заново, и один и тот же заказ попадает в систему дважды. Сценарий не редкий, а разбирают его всегда руками.

Защита — добавлять к каждому запросу идентификатор, делающий его уникальным: второй запрос с тем же идентификатором не создаёт новую запись, а возвращает результат первого. Если поставщик такого не поддерживает, держите ключ сопоставления на своей стороне и сверяйтесь перед записью. Кто побеждает, когда одна и та же запись изменилась в обеих системах, мы разбираем в материале о двусторонней синхронизации данных.

С чего начать

Оставлять проектирование лимитов напоследок — частая ошибка, и оставленное напоследок обычно переписывается. Быстрый путь состоит из трёх шагов. Сначала измерьте текущий расход: какая интеграция, в какой метод, сколько запросов в сутки отправляет. Затем выясните, какая доля этого трафика бесполезна; опрашивающие запросы, ничего не возвращающие, обычно возглавляют список. И только после этого поставьте оставшийся трафик в очередь с приоритетами.

Ни один из трёх шагов не требует переговоров с поставщиком, и вместе они чаще всего снимают саму необходимость просить расширение. Просить не зазорно, но решать проектную проблему договором значит перенести её на следующий этап роста. К той же логике относится вынос тяжёлой аналитики из операционного API; этот раздел мы описываем в материале об интеграции с хранилищем данных.

Самое практичное противоядие от борьбы с лимитами — сократить число систем, делающих одну и ту же работу: когда продажи, финансовый учёт и отчётность живут на одной записи, между системами просто нечего гонять. В Rocketly эти потоки собраны на одной платформе, поэтому число внешних интеграций остаётся небольшим; создать бесплатный аккаунт и собрать более простую карту интеграций можно с самого начала.