Коды ошибок Meta CAPI: полный справочник по диагностике

Как Meta CAPI сообщает об ошибках

Meta Conversions API нарочно молчалив: он возвращает минимум данных ради экономии трафика. Валидный payload зарабатывает 2xx-ответ без церемоний. Невалидный приезжает как 4xx с компактным error-объектом общей для Graph API формы:

{
  "error": {
    "message": "Message describing the error",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 460,
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}

Читайте в таком порядке: code выбирает семейство сбоя, error_subcode сужает его, error_user_msg часто содержит человекочитаемую инструкцию, а fbtrace_id - идентификатор, по которому поддержка Meta находит запрос в своих логах. Если вы работаете через трекер, этот JSON виден в логе исходящих постбеков по каждому упавшему S2S-вызову - это первая точка чтения, а не рекламный кабинет.

Один нюанс про батчи: Meta документирует, что при невалидном событии в батче запрос возвращает ошибку, но валидные события с event_id всё равно принимаются; когда вы почините сломанные записи и переотправите весь батч, уже сохранённые события отбросятся как дубли и не задвоятся. Провал батча - не повод паниковать и пересобирать очередь, а повод починить названные события и переотправить. Одно исключение есть: 7-дневный лимит импорта отклоняет весь запрос, включая валидные события, - об этом ниже.

Коды ошибок Meta CAPI, которые вы реально увидите

Meta ведёт длинный error-справочник для Marketing API; на доставку конверсий почти весь урон приходится на короткий набор:

Два кода заслуживают отдельных статей, а не строк таблицы. Ошибка 2804003 - это 7-дневный лимит импорта: Meta отклоняет весь запрос, если хоть один event_time старше 7 дней; у неё есть отдельный разбор - почему Meta отклоняет события старше 7 дней. Код 368 означает, что аккаунт или действие временно заблокированы за нарушение политик: тут нет payload-фикса, решение идёт через Account Quality, а не через интеграцию.

Чиним ошибку 100: invalid parameter

Ошибка 100 - генерический «невалидный параметр», и стреляет она по структурным проблемам payload: отсутствующее обязательное поле (event_name, event_time, action_source), невалидное значение enum, таймстемп в миллисекундах вместо Unix-секунд, кривое поле валюты или суммы. Ловушка: нехэшированные данные пользователя обычно НЕ возвращают ошибку 100 - Meta принимает событие и молча игнорирует кривое поле, показывая warning и тихо роняя Event Match Quality. Поэтому дисциплина хэширования важна, но живёт она в секции валидации, а не в логе ошибок; механика - в Event Match Quality.

Опасный вариант - 100 с error_subcode: 33. По справочнику Meta это unsupported post request: ваш access token не прикреплён к рекламному аккаунту, владеющему объектом, как system user с нужными правами. Официальное восстановление административное: access token должен принадлежать system user с нужными правами на ассет - в Business Settings путь такой: Business Settings -> System Users -> ваш пользователь -> Add Assets, где пикселю или датасету (и рекламному аккаунту) выдаётся полный контроль, после чего вызов повторяется. Никакие правки payload сабкод 33 не чинят - это проблема структуры доступа.

Существуют и другие сабкоды 100 - устаревшие категории таргетинга, неподдерживаемые комбинации задач; пара message+subcode всегда называет конкретную проблему. Верьте паре, чините названное поле и только потом переотправляйте.

Чиним 190 и 102: токены и сессии

Код 190 - OAuth access token невалиден или истёк; код 102 - сессия больше не действительна; код 200 - токен жив, но у него нет права на конкретное действие или ассет - классика расшаренных пикселей, когда ассет принадлежит другому бизнесу, не токену. Симптом у всех одинаковый: события, которые доставлялись вчера, сегодня падают - часто после ротации токена, ухода сотрудника или реорганизации в Business Manager.

Путь восстановления: сгенерируйте свежий долгоживущий access token для system user и проверьте, что у этого system user есть роль на рекламном аккаунте, владеющем пикселем. Важно, где живут токены: токен, вставленный в поле трекера, переменную tag manager или cron-скрипт, умирает тихо, когда базовый креденшел протухает. Полный процесс выдачи - в гайде по Meta Pixel ID и access token. Аутентификационные сабкоды (463, 467, 460) уточняют причину - истёк, отозван, сменился пароль - но фикс сходится к тому же свежему токену.

Чиним троттлинг: коды 4 и 17

Код 4 - лимит запросов на уровне приложения; код 17 - на уровне пользователя. Рядом код 1 - неизвестная ошибка, обычно временный сбой на стороне Meta: относитесь как к 5xx и просто ретраите с backoff, payload не трогайте. Код 10 - вовсе не троттлинг, а отказ в правах, он относится к токен-фиксам выше. Оба означают троттлинг, а не отказ в данных: Meta документирует их как временные - подождать или пересмотреть объём запросов. Доставка конверсий усугубляет проблему, потому что ретраи сталкиваются с обычным трафиком: очередь, которая тут же переотправляет упавшие батчи, долбит API ровно в момент, когда он и так перегружен.

Механический фикс тот же, что Meta рекомендует для сетевых ошибок: ретраить не-client ошибки с backoff и держать таймаут запроса 1500 миллисекунд - большинство ответов CAPI приходит быстрее 600 мс, так что более длинный клиентский таймаут просто занимает воркеров. Укрупняйте батчи (до 1000 событий в data) и разносите джобы по времени, чтобы несколько кампаний не стреляли в одну секунду.

7-дневный лимит и безопасные ретраи

Правила event_time кусают опаздывающие данные: серверное событие может нести время раньше момента отправки, но не более чем на 7 дней назад - отправите старее, Meta отклонит весь запрос и не обработает ничего. Для офлайн-событий с action_source: physical_store окно шире - 62 дня. Глубокий кейс разобран в гайде 2804003, механика задержек за ним - в задержках Meta CAPI.

Поэтому батч-ретраи безопасны при правильном исполнении. Валидные уже принятые события при переотправке отбрасываются как дубли - дедупликация ключуется на event_id и event_name и хранит первую копию. Правильный ретрай-луп: почините все названные невалидные события, переотправьте весь батч, дайте дедупликации схлопнуть пересечение. Никогда не переотправляйте с новыми event ID - так одна конверсия станет двумя.

Валидация доставки после фиксов

Когда ошибки стихли, проверьте, что Meta реально получила. Events Manager → Overview для вашего пикселя показывает счётчики raw, matched и attributed событий плюс канал доставки по каждому - разрыв между raw и matched прячёт проблемы хэширования даже там, где ошибок не возвращалось. Перед выкаткой изменений payload прогоните их в Meta Test Events - инструмент печатает валидацию на уровне полей, не пачкая продакшн-статистику.

Структурный слой вокруг этих кодов - как серверные события соотносятся с пикселем и когда какой канал стреляет - собирает полный гайд по Meta Conversions API, а механику анти-задвоений описывает дедупликация по event ID. Если вы маршрутизируете постбеки трекеров в Meta и хотите автоматизировать доставку, MOST централизованно делает ретраи и дедупликацию; бесплатный ручной путь живёт на Pixel Activator.

Sources