Коды ошибок WhatsApp Cloud API: значения и способы исправления

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

Где появляются ошибки WhatsApp Cloud API?

Ошибки появляются в двух местах, и фиксировать нужно оба. Ошибки запроса приходят сразу в ответе API, а ошибки доставки — позже в вебхуке статусов.

• Синхронные ошибки. Запрос на отправку отклоняется, а ответ содержит объект error с полями code, message, type и часто error_data.details. Типичные примеры — истёкшие токены, отсутствующие параметры и несовпадения с шаблоном.
• Асинхронные ошибки. Запрос на отправку проходит успешно и возвращает ID сообщения, но позже вебхук сообщает status: failed с массивом errors. Типичные примеры — закрытое окно обслуживания, недоставляемые получатели и маркетинговые лимиты.

Распространённая ошибка — логировать только HTTP-ответ. Команда считает, что кампания прошла успешно, потому что на каждый запрос вернулся ID сообщения, хотя сотни сообщений не были доставлены, о чём сообщили вебхуки. О том, как связаны статусы между собой, читайте в статье sent, delivered, read и failed: что означают статусы.

Какие коды ошибок WhatsApp встречаются чаще всего?

В таблице собраны коды, с которыми сталкивается большинство команд, — с подсказкой, что делать дальше. Описания пересказывают справочник Meta.

Как исправить ошибки, из-за которых чаще всего срываются кампании?

На практике большинство сбоев вызывает несколько кодов. Для каждого есть чёткое правило.

131047: окно обслуживания закрыто

Клиент писал последний раз более 24 часов назад. Текст в свободной форме, медиафайлы и интерактивные сообщения разрешены только внутри 24-часового окна обслуживания клиента; за его пределами нужно использовать одобренный шаблон, см. 24-часовое окно обслуживания клиента. Операторы часто сталкиваются с этой ошибкой, отвечая в старом чате. Показывайте операторам статус окна и предлагайте выбор шаблона, когда оно истекло.

131026: сообщение не доставлено

Начните с проверки номеров: международный формат, правильный код страны, без ведущего нуля после кода. Затем примите, что некоторых номеров просто нет в WhatsApp или на них установлена старая версия приложения. Для срочных сообщений, например OTP-кодов (одноразовых кодов), используйте резервный канал (fallback) — SMS. См. WhatsApp, SMS и RCS: сравнение.

131049 и 131050: маркетинговые лимиты и отписки

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

130429, 131048 и 131056: слишком быстрая или слишком объёмная отправка

130429 — это пропускная способность: поставьте сообщения в очередь и применяйте нарастающую паузу (backoff). 131056 относится к паре «отправитель — получатель»: вы пишете одному человеку слишком часто. 131048 — сигнал о качестве номера-отправителя; он требует исправить содержание и таргетинг, а не повторять отправку. См. лимиты сообщений и рейтинг качества.

132000, 132001 и 132012: несовпадения с шаблоном

Почти всегда это ошибки интеграции. Название шаблона, код языка (например, ar и en_US) и число переменных должны точно совпадать с одобренным вариантом. Напишите тест, который отправляет каждый шаблон с тестовыми значениями при любом его изменении.

Политика повторных попыток, которую можно внедрить

Используйте этот чек-лист, чтобы автоматически классифицировать каждый сбой.

1. Логируйте код, заголовок, error_data.details, ID сообщения, получателя и название шаблона.
2. Никогда не повторяйте 131050, 131021, 132016, 368 и 131031. Об ошибках 368 и 131031 сразу сообщайте администратору.
3. Сначала исправьте, потом повторите ошибки авторизации (0, 190, 10), параметров (131008, 131009, 135000), шаблонов (от 132000 до 132015) и оплаты (131042). Оповестите ответственную команду.
4. Подождите и повторите при 130429, 4, 80007, 131016 и 131057, используя экспоненциальную паузу (backoff) с верхним пределом.
5. Смените канал или тип сообщения при 131047 (шаблон) и 131026 (SMS или e-mail).
6. Подождите 24 часа или больше при 131049 и пересмотрите частоту кампаний.
7. Показывайте сбои по кодам в отчётах по кампаниям, а не одной общей цифрой «не доставлено».

Пример из практики: неудавшаяся акция ритейлера из Эр-Рияда

Это условный пример. Компания «Najd Home» отправляет маркетинговый шаблон 20 000 клиентов, давших согласие на получение сообщений (opt-in). API принимает все запросы, но вебхуки статусов показывают около 1 400 сбоев.

Если сгруппировать их по кодам, картина становится ясной. Самая большая группа — 131049: команда исключает этих пользователей из двух следующих рассылок и снижает недельную частоту. Меньшая группа — 131026: анализ показывает, что многие номера хранятся с локальным ведущим нулём, и проблему решает нормализация номеров. Несколько пользователей с кодом 131050 навсегда исключены из маркетинговых рассылок. Несколько ошибок 130429 возникли из-за первоначального всплеска отправки, поэтому теперь отправка идёт равномерно через очередь.

Типичные ошибки и честные ограничения

• Считать любой сбой поводом для повтора. Это впустую расходует бюджет и может снизить качество.
• Зашивать тексты Meta в код. Meta обновляет заголовки и описания; стройте логику на числовом коде и ведите справочник, который можно обновлять.
• Игнорировать error_data.details. Там часто указан конкретный проблемный параметр.
• Не у каждого сбоя есть решение. Некоторых получателей не удаётся достичь в WhatsApp, а Meta не объясняет каждое решение по 131049. Заранее предусмотрите альтернативный канал.

Чем помогает OmniChannels.ai

OmniChannels.ai на базе BroadNet Technologies предоставляет отчёты о доставке в сводном и расширенном видах с фильтрами и экспортом в CSV, чтобы можно было анализировать недоставленные сообщения по кампаниям. Резервный канал (fallback) может повторно отправить сообщение через RCS или SMS, если не удалось доставить его в WhatsApp, а шаблоны отображаются в предпросмотре на макете телефона, и их одобрение отслеживается, что снижает число ошибок из-за несовпадений. Вебхуки передают статусы FAILED и REJECTED в едином нормализованном формате, а в открытой документации для разработчиков есть справочник по ошибкам и лимитам.