Лимиты Ozon Seller API: за что прилетает 429 и как развести запросы по методам

Интеграция работает неделю, а в понедельник утром остатки не обновились, заказы приехали в кабинет с опозданием на сорок минут, и в логе стена из 429 Too Many Requests. Почти всегда дело не в «плохом коде» и не в сбое площадки: просто все процессы стартуют в одну и ту же минуту и ходят в API без общего счётчика. Ниже — как устроены квоты по группам методов, почему лимит делится на магазин, а не на ключ, как правильно повторять запрос после 429 и как разложить опросы по расписанию, чтобы интеграция перестала падать по утрам.

Что означает 429 и чем он отличается от остальных ошибок

429 — это «квота исчерпана, запрос не выполнен». Ключевое слово здесь второе: до бизнес-логики Ozon запрос не дошёл, ничего не изменилось, товар не отгружен, цена не записана. Значит, повторить его безопасно — в отличие от таймаута или 5xx, где состояние на стороне площадки неизвестно и слепой повтор может дать дубль.

Остальные коды лечатся не паузой, а руками. 401 — ключ неверный или отозван. 403 — у ключа нет прав на метод либо вы стучитесь не в тот контур. 400 — тело запроса не то, что ждёт метод. Повторять их с нарастающей задержкой бессмысленно: вы просто растянете падение на полчаса вместо секунды.

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

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

Квота делится на магазин, а не на ваш скрипт

Лимит считается по Client-Id — то есть на магазин целиком, а не на конкретный ключ или процесс. Для того, кто впервые ловит 429, это главный сюрприз: ваш скрипт делает три запроса в минуту и всё равно получает отказ.

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

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

Второе: контуры разные. Seller API (api-seller.ozon.ru, заголовки Client-Id и Api-Key) и Performance API для рекламы (api-performance.ozon.ru, Bearer-токен по client_id и client_secret) живут с раздельными ограничениями. Токен Performance API короткоживущий, порядка получаса, и его надо кэшировать: запрос токена перед каждым вызовом — классический способ упереться в лимит на ровном месте.

Третье: внутри Seller API лимиты не одинаковые. Аналитические и отчётные методы ограничены жёстче всего — обычно это единицы вызовов в минуту. Операционные списки отправлений терпят заметно больше. Методы записи ограничены дважды: по частоте и по количеству позиций в одном вызове. Точные цифры по методам площадка меняет, поэтому сверяйтесь с базой знаний Ozon Seller и документацией метода, а не с чужим постом двухлетней давности.

Как развести методы по частоте

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

Отдельно про отчёты. Схема «создать отчёт — узнать статус — скачать файл» экономит квоту в разы: пятьсот карточек, вытянутых по одной, — это пятьсот запросов, а та же информация одним отчётом — три запроса и файл на диске.

Повторы: растущая пауза, джиттер и предел попыток

Схема повтора после 429 состоит из четырёх правил, и пропуск любого из них возвращает проблему.

Пауза растёт. 1, 2, 4, 8, 16 секунд. Фиксированная пауза в полсекунды не помогает: вы продолжаете долбить в закрытое окно с чуть меньшей частотой.

Слушайте Retry-After, если он пришёл. Заголовок с числом секунд важнее вашей формулы — площадка прямо говорит, когда можно. Если заголовка нет, работает формула.

Добавьте джиттер. Десять воркеров, получивших 429 в одну секунду, по чистой формуле повторят тоже в одну секунду — и снова получат 429. Случайный разброс ±30 % от базовой паузы разводит повторы во времени, и волна рассыпается на отдельные запросы.

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

Что повторять нельзя: 400, 401, 403 — ответ не изменится. Отдельная история — таймаут и 5xx на методах записи (отгрузка, сборка, изменение статуса). Там запрос мог дойти и выполниться, а ответ потеряться. Перед повтором такие вызовы надо сверять чтением: получить текущий статус отправления и только потом решать. Иначе получите два комплекта этикеток на одну посылку — проверено, неприятно.

Расписание опросов: минуты, а не «каждые пять минут»

Фраза «обновляем каждые 5 минут» ничего не говорит о нагрузке. Значение имеет то, в какие именно минуты. Если задачи в кроне стоят как */5, */10, */15, */30 и 0 * * * *, то ровно в :00 они стартуют все пять разом — и утренний пик заказов приходится на этот же момент.

Разносите старты вручную. У нас сейчас так: отправления — на :02, :07, :12 и дальше с шагом 5; остатки — на :05 и :35; цены — на :16 и :46; каталог — в 04:10; финансовые транзакции — в 06:20; аналитика — в 03:40. Никакие две задачи не начинаются в одну минуту, и это половина эффекта от всей переделки.

Учитывайте лаг данных. Финансовые транзакции за вчера в 00:05 запрашивать бесполезно — часть проводок ещё не создана, вы потратите квоту и получите неполную картину, которую потом придётся перезапрашивать. Аналитика за сутки тоже дозревает: ночное окно не только разгружает лимит, но и даёт более полные цифры.

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

Один клиент с лимитером вместо пауз в каждом скрипте

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

1. Единая обёртка над HTTP. Все процессы ходят в Ozon через один клиент. Там же живут заголовки, логирование, разбор кодов и повторы — в одном месте, а не в каждом файле.
2. Токен-бакет на группу методов. Отдельный счётчик для тяжёлой аналитики, отдельный для операционных списков, отдельный для записи. Исчерпался один — остальные продолжают работать.
3. Семафор на параллелизм. Два-четыре одновременных запроса вместо двадцати. Пропускная способность почти та же, доля 429 падает в разы.
4. Очередь с приоритетом. Отгрузка отправления важнее обновления описания карточки. При нехватке квоты задерживается второе, а не первое.
5. Метрика вместо ощущений. Количество запросов в сутки по методам и доля 429 — две цифры, по которым видно, помогла правка или нет.

Разбор: как мы перестали ловить 429 каждое утро

Симптом был стабильный: с 9:00 до 9:06 доля ответов 429 доходила до 38 %, остатки по 240 SKU обновлялись 11 минут вместо одной, часть значений не доезжала вовсе. Дважды за месяц Ozon продал товар, которого физически не было: отмена по нашей вине, объяснение покупателю и минус в проценте отмен, который тянет вниз рейтинг магазина.

Разобрали лог за неделю и получили 14 200 запросов в сутки. Из них 9 600 — запросы карточки товара по одному SKU в цикле, хотя каталог у нас меняется раз в неделю. Ещё 2 880 — опрос списка новых отправлений раз в минуту, причём сразу двумя процессами: сервисом учёта и нашим же скриптом, по 1 440 вызовов с каждого. В 97 % ответов список был ровно тот же, что и минуту назад.

Сделали четыре вещи. Каталог переехал в локальную таблицу с обновлением раз в сутки в 04:10. Остатки пошли батчами по 100 позиций (предел на один вызов уточняйте в документации метода) — 240 вызовов превратились в 3. Старты задач развели по минутам. Все запросы завели через один клиент с токен-бакетом, семафором на 3 параллельных и повторами по схеме 1-2-4-8-16 с джиттером.

Стало 2 100 запросов в сутки, доля 429 — 0,2 %, обновление остатков — 40 секунд, отмен по причине «нет товара» из-за рассинхрона больше не было. Главный вывод неприятный: 85 % запросов были лишними изначально, и лимит просто показал это раньше, чем мы сами догадались посмотреть. Свою аналитику по остаткам и прибыли мы с тех пор считаем в Starbox AI, а собственный скрипт оставили только под нестандартные выгрузки — и квоту они между собой больше не делят.

Что делать, когда лимит всё равно мешает

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

Убирайте дубли источников. Если push-уведомления по заказам уже настроены, старый опрос раз в минуту нужно выключить, а не оставлять «на всякий случай»: событие придёт двумя путями, квота потратится дважды.

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

Если после всего 429 остаётся на конкретном методе, идите в поддержку с фактурой: название метода, время в UTC, Client-Id, реальная частота вызовов, идентификатор запроса из заголовков ответа (если метод его возвращает) и кусок лога. Api-Key при этом не прикладывайте ни в каком виде. С формулировкой «у меня всё падает» разговор не получится, с логом — вполне.

FAQ

Сколько запросов в минуту разрешает Ozon Seller API?

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

Почему 429 приходит, хотя запросов у меня немного?

Потому что квота считается на магазин целиком. В ваш кабинет параллельно ходят сервис учёта, внешняя аналитика, скрипт в таблице и любая интеграция, которой когда-то выдали ключ. Ваши три запроса в минуту складываются с их сотней. Начните с ревизии выпущенных ключей в разделе «Настройки → Seller API» и отзовите всё, что уже не используется.

Поможет ли второй API-ключ обойти лимит?

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

Нужно ли повторять запрос после 429 и как быстро?

Нужно: запрос не выполнен, данные не изменились, повтор безопасен. Пауза должна расти — 1, 2, 4, 8, 16 секунд — и содержать случайный разброс порядка 30 %, чтобы параллельные процессы не повторяли одновременно. Если в ответе пришёл заголовок Retry-After, ориентируйтесь на него, а не на свою формулу.

Считается ли Performance API в ту же квоту, что Seller API?

Нет, рекламный Performance API — отдельный контур со своей авторизацией и своими ограничениями. Но там есть собственная ловушка: короткоживущий Bearer-токен. Если запрашивать новый токен перед каждым вызовом вместо кэширования на время его жизни, вы упрётесь в лимит уже на этапе авторизации.