Коды ошибок TikTok Events API: что означают и как их чинить
Как читать ошибку TikTok Events API
TikTok Events API 2.0 отвечает на любой запрос одной и той же структурой: code (возвратный код API), message с деталями сбоя и request_id - лог-ID вашего запроса. При успехе API возвращает HTTP 200 с кодом 0 и пустым объектом data. При ошибке вы получаете статус 4XX или 5XX, соответствующий код и без поля data. Если вы работаете через трекер, этот JSON вы увидите в логах исходящих постбеков - Keitaro, Binom и Voluum пишут сырой ответ каждого S2S-вызова, и это самое быстрое место, где можно прочитать настоящий код.
Когда в одном запросе летит несколько событий, message указывает нулевой индекс первого невалидного события. Сообщение вида Invalid value for data.2.event_id: not a valid string означает, что третье событие в батче несёт сломанный event_id - первые два могли быть в порядке, но батч всё равно упал. Эта деталь меняет подход к кодам ошибок TikTok Events API: сначала чините названное событие и только потом переотправляете батч.
{
"code": 40002,
"message": "Invalid value for data.2.event_id: not a valid string.",
"request_id": "202308291437415F6E70BA7E095091A6F4"
}Коды, которые вы реально увидите
TikTok документирует короткий список ошибок, характерных именно для Events API 2.0, и гораздо более длинный appendix общих возвратных кодов API. Те, что бьют по доставке конверсий на практике:
| Код | HTTP | Что означает |
|---|---|---|
| 40001 | 400 | Нет прав на операции с рекламным аккаунтом |
| 40002 | 400 | Невалидный payload: сломанный JSON, отсутствующее или неверно типизированное поле, нехэшированное значение там, где требуется SHA-256, или больше 1000 событий в одном запросе |
| 40100 | 401 | Слишком много запросов: достигнут лимит эндпоинта (1000 запросов в секунду) |
| 40104 | 401 | Access token пустой |
| 40007 | 400 | Объект операции не существует: ID кампании, объявления или другого объекта в запросе ни на что не указывает |
| 40050 | 400 | Дублированный запрос: одинаковый запрос отправлен больше одного раза |
Вокруг этих четырёх - два больших семейства из общего appendix. Семейство токенов: 40102 (токен истёк), 40105 (неверный токен), 40101 (кривые параметры аутентификации - secret и app ID не совпадают), 40110 (auth-код отменён или уже использован). Семейство троттлинга: 40016 (лимит приложения), 40133 (лимит рекламного аккаунта) и 40132 (троттлинг по значению поля - QPS-лимит получил сам ваш pixel_code). А 40000 - универсальное «параметры неверны» с настоящей причиной в message.
Чиним 40001: ошибки прав
Код 40001 означает, что запрос дошёл до TikTok с валидными креденшелами, но личность за access token не имеет прав на рекламный аккаунт, которому принадлежит пиксель, куда вы шлёте события. Эндпоинт Events API у всех один - против какого аккаунта идёт действие, решают access token и pixel_code в теле запроса, - поэтому рассинхрон всегда между токеном и владельцем пикселя. Так бывает после переноса аккаунта в другой business center, когда трекер или интеграция авторизованы под личным кабинетом, или когда токену коллеги просто не выдали доступ к этому аккаунту.
Чинится не в payload - в авторизации. Прогоните OAuth-флоу заново под правильным аккаунтом и получите свежий долгоживущий access token или выдайте существующей интеграции недостающий scope. Если вы храните один токен на несколько аккаунтов, сверьте, что пиксель, в который вы шлёте, принадлежит аккаунту, доступному этому токену.
Чиним ошибки токена: 40104, 40105 и 40102
Семейство токенов ломается не так, как ошибки прав: тут TikTok вообще не получил пригодного креденшела. 40104 - access token пустой: запрос ушёл без токена, обычно потому, что поле интеграции не заполнили или переменная вернула пустоту. 40105 - токен передан, но неверный: опечатка, токен от другого приложения или обрезанное при копипасте значение. 40102 - токен истёк: короткоживущие токены умирают тихо, и первый симптом - пачка 401 в логе постбеков после периода, когда всё работало.
Лечение для всех трёх - один флоу с разными точками входа: сгенерируйте валидный долгоживущий access token для правильного аккаунта и обновите креденшел во всех местах хранения - интеграция трекера, переменная в tag manager, самописный скрипт. Выпуск и настройка токенов разобраны в гайде по TikTok Pixel ID и access token.
Чиним 40002: невалидный payload
Код 40002 - самый частый из кодов ошибок TikTok Events API в связках с трекерами, и message называет конкретное поле. Режимы отказа по частоте:
- Нехэшированные идентификаторы. Поля вроде
emailдолжны ехать как SHA-256-хэши. Отправка[email protected]вместо 64-символьной hex-строки в нижнем регистре даётInvalid value for email: not a valid SHA256-hashed string. Нормализация перед хэшем тоже важна - trim, нижний регистр, убрать разделители из телефона. Те же правила работают в TikTok enhanced matching, так что фикс заодно поднимает match rate. - Кривой формат таймстемпа. Время события - Unix-timestamp в секундах. Шаблоны трекеров и скрипты часто выдают миллисекунды (13 цифр вместо 10) или ISO-строку даты - и любой из вариантов валит валидацию.
- Кривая структура JSON. Payload не является валидным JSON или поле передано строкой там, где нужно число.
- Размер батча. Больше 1000 событий в одном запросе валит вызов - режьте очередь на меньшие батчи.
- Отсутствующие обязательные поля. Message называет недостающий параметр; верьте ему, прежде чем переписывать весь payload.
Поскольку одно невалидное событие валит весь батч, одна кривая запись из одной кампании молча роняет конверсии всех остальных кампаний в том же запросе. Увидев 40002, режьте батч, находите проиндексированное событие и чините его до переотправки.
Чиним 40100, 40133 и 40132: лимиты частоты
У семейства троттлинга один корень - слишком много запросов в секунду, но коды подсказывают, где потолок. 40100 - лимит эндпоинта в 1000 запросов в секунду. 40133 - уровень рекламного аккаунта: QPS вашего аккаунта на этом пути. 40016 - лимит вашего developer-приложения. И отдельного внимания заслуживает 40132: троттлинг по значению pixel_code, который случается, когда один пиксель долбят слишком частыми вызовами - или когда ваш access token утёк и его дёргает кто-то чужой.
Лечение механическое: экспоненциальный backoff с ретраями вместо немедленных переотправок, укрупнение мелких запросов в большие батчи (по-прежнему до 1000 событий), разнос воркеров очереди по времени. Если 40132 появился без роста вашего трафика - ротируйте токен и считайте старый скомпрометированным.
Диагностика доставки за пределами кодов ошибок
Чистый ответ API доказывает только, что TikTok получил ваши события. Следующий слой отказа - измерения, и у него свой инструментарий: Test Events в Events Manager показывает события от конкретного источника почти в реальном времени, а Web Diagnostics оценивает настройку пикселя постранично. Если API возвращает 0, но Ads Manager показывает меньше конверсий, чем трекер, вы в зоне расхождений конверсий TikTok, а не кодов ошибок.
Проверяйте три вещи по порядку. Первое - дедупликация: если для одного заказа срабатывают и пиксель, и Events API, события обязаны делить event_id, иначе TikTok насчитает две конверсии. Дедупликация по event ID схлопывает повторные отчёты об одной конверсии в одно зачтённое событие. Второе - задержка событий: TikTok ждёт события близко к реальному времени, и события, приехавшие задолго после действия, возвращаются отклонёнными или не атрибутируются. Тот же класс сбоев на Meta выделен в отдельный код - 2804003, 7-дневный лимит импорта, см. почему Meta отклоняет события старше 7 дней. Третье - автоматизация доставки: если лендингов много, Pixel Activator для TikTok Events API подключает канал без кода - сам бесплатный инструмент живёт на Pixel Activator, а гайд по TikTok Events API и пикселю собирает весь кластер.