Лимиты запросов WB API
Алгоритм Token Bucket, лимиты по типам токенов и обработка ошибки 429
Дата обновления: 03.04.2026
Зачем нужны лимиты
WB API ограничивает количество запросов, которые можно отправлять за определённый период времени. Лимиты защищают сервисы от перегрузок и обеспечивают стабильную работу API для всех пользователей.
Лимиты устанавливаются отдельно для каждого метода или группы методов. Конкретные значения указаны в документации на портале разработчиков. Если при работе с API вы получаете другие ошибки (400, 401, 403, 5XX) — обратитесь к статье «Расшифровка кодов ошибок WB API».
Как устроены лимиты
WB API использует алгоритм token bucket для равномерного распределения нагрузки. Лимиты описываются четырьмя параметрами:
Period (Период) — временной интервал, в течение которого можно отправить максимальное количество запросов.
Limit (Лимит) — максимальное количество запросов за период. Запросы должны распределяться равномерно по времени.
Interval (Интервал) — рекомендуемая пауза между запросами. Рассчитывается как Period / Limit.
Burst (Пакет) — максимальное количество запросов, которые можно отправить одновременно, без пауз.
Пример
Типичный лимит для методов категории «Маркетплейс»:
| Параметр | Значение |
|---|---|
| Period | 1 минута |
| Limit | 300 запросов |
| Interval | 200 мс |
| Burst | 20 запросов |
Это означает: вы можете отправлять до 300 запросов в минуту, с рекомендуемой паузой 200 мс между запросами. Одновременно (без паузы) можно отправить до 20 запросов.
Лимиты по типам токенов
Лимиты запросов в WB API различаются в зависимости от типа токена. У каждого типа токена — независимые лимиты.
Пример: лимиты категории «Маркетплейс»
| Тип токена | Период | Лимит | Интервал | Burst |
|---|---|---|---|---|
| Персональный | 1 минута | 300 запросов | 200 мс | 20 запросов |
| Сервисный | 1 минута | 300 запросов | 200 мс | 20 запросов |
| Базовый | 1 минута | 150 запросов | 200 мс | 10 запросов |
| Тестовый | 1 минута | 150 запросов | 200 мс | 10 запросов |
Лимиты для каждого метода указаны в его документации на портале. Значения различаются по категориям API.
Персональный и Сервисный токены
Это основные типы токенов для продуктивных интеграций. Лимиты для них — стандартные, как указано в документации к методам.
У Сервисных токенов лимит рассчитывается на все токены в пределах одного сервиса из Каталога решений для бизнеса на Wildberries (а не на тип токена в целом).
Базовый и Тестовый токены
Базовый и Тестовый — вспомогательные токены, для них установлены сниженные лимиты. Лимит распространяется на все токены в пределах одного типа.
Полный список лимитов для Базового токена по каждому методу опубликован в новости на портале разработчиков. Прайс-лист по лимитам доступен по ссылке.
Подробнее — в новости «Обновление лимитов запросов» на портале разработчиков.
Что делать, если вы используете Базовый токен
Если ваша интеграция работает через Базовый токен, рекомендуем перейти на подходящий основной тип:
- Персональный токен — для собственных программ и on-premise решений
- Сервисный токен — для облачных сервисов из Каталога решений
Подробнее о выборе типа токена — в статье «Облачный сервис или локальное решение: как отличить и какой токен выбрать»
Для сторонних сервисов, не представленных в Каталоге решений
Если ваш сервис не представлен в Каталоге решений, предусмотрена возможность идентифицировать трафик и получить доступ к API без сниженных лимитов Базового токена. Для этого необходимо отправить заявку на business-solutions@rwb.ru с информацией о сервисе.
Подача заявки — это идентификация трафика, а не авторизация сервиса и не добавление в Каталог решений. Сервисные токены в рамках этого процесса не выдаются.
Заголовки ответа
API возвращает информацию о состоянии лимитов в заголовках ответа:
X-Ratelimit-Remaining — количество запросов, которые можно отправить прямо сейчас без паузы. Значение уменьшается на 1 после каждого запроса и восстанавливается со временем. Если значение равно 0 — следующий запрос без задержки вернёт ошибку 429.
Заголовок X-Ratelimit-Remaining возвращается во всех ответах API, кроме ошибки 429. Используйте его для проактивного контроля нагрузки.
Особенности подсчёта
В некоторых случаях один запрос может учитываться как несколько. Например, запрос с ответом 409 учитывается как 5 или 10 обычных запросов в зависимости от группы методов. Точное значение указано в документации к конкретному методу — ищите примечание в блоке лимитов.
Что делать при ошибке 429
Если вы превысили лимит, API вернёт ошибку 429 Too Many Requests. В ответе будут заголовки:
| Заголовок | Описание |
|---|---|
X-Ratelimit-Retry | Через сколько секунд можно повторить запрос |
X-Ratelimit-Limit | Максимальный Burst, который восстановится |
X-Ratelimit-Reset | Через сколько секунд Burst восстановится полностью |
Пример ответа:
HTTP/1.1 429 Too Many Requests
X-Ratelimit-Reset: 29
X-Ratelimit-Retry: 2
X-Ratelimit-Limit: 10
Это означает: повторите запрос через 2 секунды; через 29 секунд лимит восстановится полностью до 10 одновременных запросов.
Обращайте внимание на поле detail в теле ответа 429 — API добавляет туда полезную информацию.
Алгоритм обработки 429
- Получите ответ 429
- Прочитайте заголовок
X-Ratelimit-Retry— он содержит количество секунд до возможного повтора - Подождите указанное время
- Повторите запрос
- Если снова 429 — увеличьте паузу (например, удвойте время ожидания)
- Не повторяйте бесконечно — установите максимальное количество попыток (3–5)
Подробнее об ошибке 429 и других кодах — в статье «Расшифровка кодов ошибок WB API». Если вместо 429 вы получаете 401 или 403 — это ошибка авторизации, а не лимитов. Разбор — в статье «Ошибки авторизации WB API и их решение».
Рекомендации по оптимизации
Распределяйте запросы равномерно. Не отправляйте все запросы пакетом — используйте интервал из документации как паузу между запросами.
Следите за X-Ratelimit-Remaining. Проверяйте заголовок ответа и при приближении к нулю увеличивайте паузу.
Обрабатывайте ошибку 429 корректно. Реализуйте логику повторных попыток (retry) с учётом заголовка X-Ratelimit-Retry. Не повторяйте запрос раньше указанного времени.
Кешируйте данные, которые меняются редко. Например, список категорий товаров или информацию о складах можно запрашивать раз в несколько часов, а не при каждой операции.
Используйте пакетные методы. Если API предоставляет метод, позволяющий обработать несколько объектов за один запрос — используйте его вместо отдельных запросов для каждого объекта.