Ozon API отвечает 403: где искать ошибку в Client-Id, ключе и правах доступа

Интеграция работала полгода, вы ничего не трогали — и вдруг каждый запрос к Ozon API возвращает 403. Или наоборот: настраиваете выгрузку первый раз, ключ скопирован из кабинета, а площадка упорно отказывает. 403 — это не «сервис лежит»: площадка вас опознала и решила, что именно этому «кому-то» сюда нельзя. Причин по сути пять, и каждая проверяется за минуту — если идти по порядку, а не перевыпускать ключ по кругу. Ниже — чем 403 отличается от 401 и 404, где чаще всего теряется доступ и что писать в поддержку, когда всё проверено.

Что говорит код ответа: 403 против 401, 404 и 429

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

Код — половина информации, вторая лежит в теле ответа, и она экономит ещё полчаса. У Seller API это JSON примерно вида {"code": 7, "message": "...", "details": []}. Число в code — не HTTP-статус, а внутренний код: отказ по правам обычно приходит с семёркой, непройденная авторизация — с шестнадцатью. Читайте message: там обычно и написано, чего не хватило. А вот если в теле лежит HTML-страница про запрет доступа, значит вас завернул не Ozon API, а промежуточный прокси, корпоративный шлюз или хостинг — чинить надо инфраструктуру, а не интеграцию. Сами коды и формулировки площадка иногда меняет, актуальные смотрите в базе знаний Ozon Seller.

Заголовки: где ломается копипаста

Seller API ждёт два заголовка: Client-Id с числовым идентификатором магазина и Api-Key с самим ключом. Оба значения лежат в кабинете продавца, в настройках, в разделе Seller API — название пункта Ozon периодически двигает, так что быстрее найти его поиском по кабинету, чем по памяти. Обе строки копируются руками, и именно здесь живёт большая часть отказов.

Что ломается чаще всего:

• невидимый пробел или перевод строки в конце ключа — двойной клик в браузере регулярно захватывает лишний символ;
• кавычки, приехавшие вместе со значением из примера в документации;
• \n, который дописал редактор при сохранении ключа в переменную окружения;
• пробел-разделитель разрядов в Client-Id, если его копировали из таблицы;
• плейсхолдер YOUR_API_KEY, который никто не заменил, — такой запрос тоже вернёт отказ, а не понятную ошибку.

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

Второй классический случай — два магазина на одном ИП. Ключ выпущен в кабинете магазина А, Client-Id подставлен от магазина Б: оба значения настоящие, оба живые, а пара недействительна. Ozon отвечает именно 403, потому что формально запрос оформлен правильно. Если у вас больше одного кабинета, держите пары в конфиге рядом и подписывайте их названием магазина, а не «ozon_key_1» и «ozon_key_2».

Ключ не того контура: Seller API против Performance API

У Ozon два независимых API, и доступы между ними не работают в обе стороны. Seller API — заказы, товары, остатки, отчёты, финансы; авторизация по паре Client-Id и Api-Key в заголовках. Performance API — рекламные кампании и статистика по ним; авторизация другая: вы отправляете client_id и client_secret, получаете временный токен и дальше ходите с ним в заголовке Authorization.

Отсюда две типовые ошибки. Первая: рекламные доступы подставили в Seller API — числового Client-Id нет, вместо него длинная строка, площадка отвечает отказом. Вторая, более коварная: Performance-токен получен успешно, но протух. Пока скрипт работает в цикле час, первые запросы проходят, а потом начинается отказ — и выглядит это как «доступ внезапно отвалился». Лечится не перевыпуском ключа, а обновлением токена по сроку жизни из ответа, с запасом в пару минут.

Ключ отозван, а сервис об этом не знает

Ключ Seller API — не вечная вещь. Он перестаёт работать, если его удалили в кабинете, перевыпустили после утечки, если сменился владелец кабинета или юрлицо, если уволенному сотруднику закрыли доступ вместе с выпущенными им ключами. Проблема в том, что интеграция об этом не узнаёт никак, кроме как через 403: письма про отозванный ключ никто не присылает.

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

После перевыпуска не забудьте главное: один ключ обычно стоит в нескольких местах — сервис аналитики, самописный скрипт, бот в Telegram, обмен со складской системой. Обновили в одном — остальные продолжат получать отказ. Мы в Starbox AI при подключении кабинета первым делом дёргаем лёгкий метод, чтобы проверить пару Client-Id и ключ до того, как запускать полную выгрузку: так проблема видна сразу, а не через сутки пустых отчётов.

Метод другой роли: ключ живой, а доступа нет

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

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

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

Разбор: 40 минут на чужой Client-Id и 19 часов молчащего бота

У нас два кабинета на одном ИП. Настраивали выгрузку заказов для второго: скопировали свежий Api-Key, а Client-Id в конфиге остался от первого магазина — строки лежали в файле друг под другом. Результат — 403 на каждом методе, включая справочники. Сорок минут мы искали проблему не там: перевыпустили ключ дважды, проверили роль, написали черновик обращения в поддержку. Нашли, только когда вывели в лог оба значения рядом и сравнили Client-Id с номером в шапке кабинета.

Второй случай в том же месяце обошёлся дороже. При закрытии доступов уволенному сотруднику отозвали ключ, который в голове у всех числился «ключом для отчётов». На нём же висел Telegram-бот с уведомлениями о новых заказах. Бот молчал 19 часов — около 214 заказов, примерно одиннадцать в час, и часть FBS уехала в сборку позже обычного. С тех пор правило простое: у каждого ключа в конфиге стоит комментарий, где он используется, и по одному ключу на сервис. Тогда отзыв ломает ровно одну интеграцию, а не половину магазина.

Что делать, если проверено всё, а 403 остаётся

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

• точное время запроса с часовым поясом — без него логи на стороне площадки не найти;
• полный путь метода вместе с версией: /v3/posting/fbs/list, а не «метод списка отправлений»;
• тело ответа целиком, а не пересказ, плюс идентификатор запроса из заголовков ответа, если он там есть;
• Client-Id — его показывать можно и нужно, это не секрет.

Ключ не отправляйте никому и ни при каких формулировках. Поддержке он не нужен, а просьба прислать ключ в переписке — повод насторожиться, кто бы её ни писал.

Дальше — обращение через кабинет, в разделе про интеграции и API. Структура, которая работает: метод, дата, что ожидали, что получили, какие шаги проверки уже сделаны. Последний пункт экономит день: без него первый ответ будет «проверьте ключ и Client-Id». И пока ждёте — не перевыпускайте ключ ещё раз: потеряете возможность воспроизвести проблему и заодно сломаете остальные интеграции, где стоит старое значение.

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

FAQ

Почему Ozon API выдаёт ошибку 403, если ключ правильный?

Чаще всего ключ действительно верный, но не соответствует переданному Client-Id: так бывает при двух кабинетах или после перевыпуска ключа в другом магазине. Вторая по частоте причина — лишний символ в значении после копирования. Сверьте Client-Id с номером кабинета и длину ключа с тем, что показывает кабинет.

Чем отличается ошибка 401 от 403 в Ozon Seller API?

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

Может ли 403 приходить из-за лимитов запросов?

Обычно превышение лимита отдаёт 429, а не 403. Но если параллельных процессов много и они бьют по площадке в несколько потоков, снизьте частоту и добавьте повтор с нарастающей паузой — это полезно в любом случае. Актуальные лимиты по методам смотрите в базе знаний Ozon Seller.

Что делать, если 403 приходит только на некоторых методах?

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

Подходит ли ключ Seller API для рекламных методов?

Нет. Реклама живёт в отдельном контуре Performance API со своей авторизацией через временный токен, и заголовки Seller API там не работают. Обратное тоже верно: рекламный токен не даст доступа к заказам и отчётам продавца.