API Wildberries: разбор ошибок и лимитов при интеграции

Интеграция с Wildberries редко ломается «сама по себе». Обычно в рекламном или операционном контуре селлера сначала появляется вполне узнаваемая картина: сервис перестал обновлять остатки, бот не забирает новые заказы, дашборд по api Wildberries статистика продаж показывает вчерашние цифры, а в логах накапливаются 401, 403 или 429. Самая дорогая ошибка здесь — воспринимать все эти коды как один общий «сбой API» и заставлять разработчика бесконечно повторять запросы.

У каждого ответа API Wildberries своя механика. 401 говорит, что проблема в самом токене. 403 — что токен существует, но ему нельзя выполнять конкретное действие. 429 означает, что интеграция съела доступный темп запросов и теперь должна подождать. А 409 в отдельных методах способен неожиданно дорого обойтись именно по лимитам: один такой ответ в категории «Маркетплейс» может списать ресурс, сопоставимый с десятью обычными запросами.

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

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

Сначала токен, потом методы: где начинается нормальная интеграция

WB API — это HTTP REST API. В каждом запросе интеграция передаёт токен в заголовке авторизации в формате Authorization: Bearer <токен>. Внешне это простая конструкция, но именно на этом уровне возникает большая часть ошибок в самописных скриптах, связках с 1С и быстро собранных облачных сервисах.

Wildberries использует четыре типа токенов. Выбирать их нужно не по принципу «какой удалось создать», а под архитектуру конкретной автоматизации.

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

Токен должен быть отдельным объектом учёта, а не строкой, которую однажды скопировали разработчику. Для каждого доступа полезно зафиксировать:

• какой сервис или модуль его использует: CRM, учётная система, бот остатков, аналитика, модуль цен, рекламная автоматизация;
• кто владелец интеграции внутри компании;
• какие категории и действия нужны: чтение, запись, работа с конкретным разделом API;
• дату выпуска и контрольную дату до истечения 180 дней;
• среду работы — тестовая или боевая;
• план отзыва при смене подрядчика либо сотрудника.

Особенно внимательно стоит смотреть на облачные решения. Персональный токен логичен для скрипта, который работает на сервере самого продавца. Но если доступ уходит во внешний SaaS, это уже другой сценарий. Попытка использовать Персональный токен в облачном сервисе — одна из документированных причин ответа 403. То есть «ключ рабочий, вчера всё выгружалось» не является доказательством, что схема авторизации выбрана правильно.

Токен — не пароль «от API вообще», а пропуск с конкретным типом, правами и сроком жизни.

Лимит запросов API Wildberries: почему счётчик не равен числу запросов в минуту

Самая опасная привычка в интеграциях — взять где-то цифру «300 запросов в минуту», поставить задержку 200 миллисекунд и считать, что вопрос закрыт. Для части методов категории «Маркетплейс» действительно приводится такой пример: 300 запросов за минуту, рекомендуемый интервал 200 мс и Burst 20. Но это не универсальный лимит для всех API Wildberries.

У разных групп методов свои параметры. Например, для методов категории «Контент» в документации указан другой режим: 100 запросов в минуту, интервал 600 мс, Burst 5. У операций с ценами и скидками — ещё один профиль ограничений. Нельзя проектировать интеграцию по одному числу, даже если оно работало в модуле заказов: выгрузка карточек, остатки, цены и статистика продаж могут жить в разных лимитных контурах.

Механика построена на алгоритме Token Bucket — «ведро токенов». Упрощённо это работает так:

1. Для метода или группы методов API устанавливает запас доступных запросов — Burst.

2. Пока запас есть, несколько запросов могут пройти одновременно.

3. Затем токены постепенно восстанавливаются с заданным интервалом.

4. Если интеграция отправляет новый запрос, когда доступных токенов нет, сервер отвечает 429 Too Many Requests.

В документации API лимиты описываются четырьмя параметрами:

В реальном кабинете селлера проблема возникает не от одного аккуратного запроса. Её создаёт параллелизм. Например, утром запускается выгрузка api Wildberries статистика продаж, одновременно CRM забирает заказы, сервис остатков обновляет данные для всех SKU, а модуль ценообразования отправляет изменения по акциям. Если эти процессы используют общий контур лимита и не знают друг о друге, каждый по отдельности выглядит безопасным, но суммарно они быстро выбивают Burst.

Поэтому в зрелой интеграции нужен не просто sleep после каждого обращения, а диспетчер запросов. Его задача — собрать вызовы в очередь по группам методов, учитывать допустимый параллелизм и не выпускать пачку запросов только потому, что в очереди накопилось 500 карточек.

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

Какие заголовки нужно писать в логи

У многих интеграций лог выглядит так: время, URL, код ответа. Для разбора 429 этого недостаточно. Нужны заголовки лимитирования — без них разработчик видит факт отказа, но не видит, когда и почему можно продолжить работу.

Ключевой заголовок — X-Ratelimit-Remaining. Он показывает, сколько запросов API готов принять сейчас без паузы. После вызовов значение уменьшается, затем восстанавливается со временем. Если оно дошло до нуля, следующий немедленный вызов с высокой вероятностью закончится 429.

При ответе 429 особенно полезны три поля:

• X-Ratelimit-Retry — сколько секунд ждать до повторной попытки;
• X-Ratelimit-Reset — через какое время Burst восстановится полностью;
• X-Ratelimit-Limit — каким будет максимальный Burst после восстановления.

Это не декоративные данные. Если сервер сообщает X-Ratelimit-Retry: 2, интеграция должна отложить повтор на две секунды, а не делать десять запросов подряд «на всякий случай». После каждого такого лишнего вызова очередь не становится ближе к выполнению — она только производит шум в логах и добавляет нагрузку.

Ошибки API Wildberries: как отличить 401 от 403 и не лечить доступ ретраями

В рекламном кабинете мы привыкли, что падение показов иногда можно исправить ставкой, семантикой или сменой стратегии. В API логика жёстче: если причина в авторизации, никакой retry, увеличение таймаута или новый прокси её не исправят. Сначала надо прочитать detail в теле ответа и сопоставить код с конкретным сценарием.

401 Unauthorized: токен не принимается

Ответ 401 означает, что сервер не может авторизовать переданный токен. Обычно причина находится в одном из четырёх мест:

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

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

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

403 Forbidden: ключ валиден, но действие запрещено

403 часто ошибочно называют «нерабочим токеном». Это не так. Токен прошёл авторизацию, но у него нет права на этот метод или сценарий.

Причины обычно такие:

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

Это принципиальная разница. При 401 нужно искать срок жизни, отзыв или повреждение секрета. При 403 нужно пересматривать матрицу прав и тип токена. Если разработчик меняет URL, добавляет повторные попытки и ждёт, что 403 «пройдёт позже», он просто маскирует архитектурную ошибку.

Для селлера здесь есть простой управленческий вывод: доступы нельзя выдавать с формулировкой «для аналитики». Надо описывать действие. «Сервис читает заказы и остатки», «модуль выгружает статистику», «система отправляет обновления цен». Тогда несоответствие прав видно ещё до запуска.

409: не только конфликт данных, но и расход лимита

С 409 нужно работать осторожнее, чем принято. В прикладной логике этот ответ часто означает конфликт состояния: операция не может быть выполнена в текущем виде. Но для части методов категории «Маркетплейс» у него есть дополнительный эффект — такой запрос способен списать лимит как десять обычных.

Именно поэтому нельзя ставить 409 в один ряд с безобидными «бизнесовыми» ответами и запускать агрессивный retry. Если интеграция отправила конфликтную операцию 20 раз, она может не только не решить проблему данных, но и закрыть себе доступ к следующей полезной пачке обращений.

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

409 — это сигнал остановить сценарий и сверить состояние данных, а не команда «нажать повторить ещё раз».

Как обрабатывать 429 и не устроить себе самоблокировку

429 Too Many Requests — не бан и не повод срочно выпускать новый токен. Это штатный ответ системы ограничений: конкретный поток запросов превысил текущую доступную ёмкость. В большинстве случаев API само подсказывает, как из этой точки выйти.

Рабочая стратегия выглядит так.

1. Остановить немедленные повторы по этому маршруту. Если один воркер получил 429, он не должен продолжать штурмовать endpoint. При нескольких параллельных воркерах сигнал необходимо передать всему пулу, иначе один процесс ждёт, а остальные добивают лимит.

2. Считать X-Ratelimit-Retry и поставить отложенную задачу. Время ожидания задаёт сервер. Оно важнее локального правила «повторяем через секунду», потому что локальное правило не знает текущего состояния ведра токенов.

3. Сохранять счётчик попыток. Официальная рекомендация ограничивает число повторов диапазоном 3–5. Бесконечный retry — плохая инженерная привычка: он маскирует ошибку планировщика и создаёт бесконечную очередь из одних и тех же задач.

4. После повторного 429 снижать конкурентность, а не только увеличивать паузу. Если процесс использует 20 параллельных потоков, задержка в каждом из них может не помочь. Нужен общий ограничитель скорости на группу методов.

5. Разделять критичные и фоновые задачи. Обновление цен, забор новых заказов и фоновая историческая выгрузка не должны бороться за один последний запрос. В очереди приоритетов операционные действия получают более высокий класс, а тяжёлые пересчёты уходят в свободное окно.

6. Не повторять операции записи вслепую после сетевого сбоя. Для POST, PUT, PATCH и DELETE безопасная стратегия зависит от конкретного метода и бизнес-операции. Если ответ потерялся по сети, это не гарантирует, что сервер ничего не применил. Идемпотентность нужно проверять по документации нужного метода, а не предполагать по умолчанию.

В системах, где автоматизация касается и рекламы, и операционки, полезно показывать лимит не только разработчику в техническом логе. Менеджер должен видеть хотя бы три бизнес-сигнала: процент успешных вызовов, долю 429 по каждому модулю и возраст последнего успешного обновления данных. Иначе отчёт выглядит «живым», хотя фактически он не обновлялся уже несколько часов.

Почему фиксированная задержка не всегда спасает

Фиксированный интервал между запросами может работать в одном скрипте и разваливаться после подключения второго. Причина в том, что ограничение применяется к методу или группе методов, а не к представлению команды о том, кто именно сейчас делает вызов.

Например, специалист подключил новый парсер для мониторинга карточек конкурентов. Он настроил «безопасные» 500 миллисекунд между запросами. Но в это же время CRM с тем же доступом забирает заказы, а сервис аналитики обновляет показатели по артикулам. Каждый компонент соблюдает собственную паузу, но общий ритм уже выше разрешённого.

Поэтому правильная единица управления — не отдельный скрипт, а централизованный лимитер. Он должен знать, к какой группе относится вызов, сколько осталось запросов, есть ли активный cooldown после 429 и какой приоритет у задачи.

Что изменилось в лимитах в 2026 году

С 30 марта 2026 года Wildberries разграничил лимиты запросов по типам токенов. Это изменение особенно заметно для продавцов, у которых исторически один и тот же код используется с разными ключами: тестовым, базовым, персональным и сервисным.

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

Практически это меняет подход к нагрузочному тестированию. Проверять нужно не просто «выдерживает ли наш модуль 100 запросов», а:

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

Если у селлера несколько магазинов и набор сервисов — 1С, CRM, аналитика, модуль цен, бот уведомлений, — полезно провести короткий аудит не по брендам сервисов, а по потоку вызовов. Один лист с таблицей «сервис → токен → методы → периодичность → права → владелец» часто находит проблему быстрее, чем неделя чтения логов.

Интеграция должна быть бережной к API и к данным

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

Базовая дисциплина здесь довольно конкретна: выбрать правильный тип токена, вести реестр доступов, читать detail и заголовки ответа, лимитировать запросы по группам методов, не путать 401 с 403 и не лечить 429 бесконечными повторами. Важно также не переносить лимиты с одного endpoint на другой: цифра, подходящая для категории «Маркетплейс», не становится правилом для контента, цен или статистики.

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