Коды ошибок WhatsApp Cloud API
Здесь собраны все коды ошибок WhatsApp Cloud API, которые мы документируем, в одной таблице с объяснением каждого и указанием, поможет ли повторная отправка. В большинстве случаев нет: ошибка предсказуема, поэтому тот же запрос снова завершится так же, а цикл повторов превратит неверный запрос в ограничение частоты запросов.
Request
| Code | What it means | Retry |
|---|---|---|
| 100 | A parameter is unsupported, misspelled or malformed. | No |
| 131008 | A required parameter was not included at all. | No |
| 131009 | A parameter is present with a value the endpoint rejects. | No |
| 131021 | Sender and recipient are the same number. | No |
| 131051 | The message type is not supported, often a Coexistence limit. | No |
| 131052 | Meta could not download media a customer sent. | No |
| 131053 | Meta could not upload media you sent. Size, format or reach. | No |
Template
| Code | What it means | Retry |
|---|---|---|
| 132000 | The number of parameters does not match the template. | No |
| 132001 | No template exists with that name and language pair. | No |
| 132007 | The template breaks messaging policy. Rewrite and resubmit. | No |
| 132012 | Parameter format does not match what the template defines. | No |
| 132015 | The template is paused after a quality decline. Temporary. | Wait |
| 132016 | The template is permanently disabled. It will not come back. | No |
Window and recipient
Registration and PIN
| Code | What it means | Retry |
|---|---|---|
| 131045 | The number was never registered for Cloud API messaging. | No |
| 133010 | The number is not registered. Registration must be completed. | No |
| 133006 | The number must be verified before it can be registered. | No |
| 133005 | The two-step verification PIN was wrong. Stop guessing. | No |
| 133008 | Too many PIN attempts. Registration is locked for a period. | Wait |
Access and account
| Code | What it means | Retry |
|---|---|---|
| 190 | The access token expired or was invalidated. | No |
| 368 | The account is restricted after a policy violation. | No |
| 131031 | The account is restricted, or its data does not match Meta's. | No |
| 131042 | A payment problem on the business account blocks sending. | No |
| 131049 | Meta blocked the message to protect ecosystem health. | No |
Rate limits
Transient
Coexistence sync
Как читать столбец повторной отправки
В нём три значения, и ошибочный выбор между ними является самой дорогой ошибкой во всей этой справке.
«Нет» означает, что ошибка предсказуема. Не сработал запрос, шаблон или состояние получателя, поэтому повторная отправка того же запроса даст ту же ошибку и потратит пропускную способность, которая пригодится позже. «Да» означает, что ошибка произошла на стороне Meta и экспоненциальная задержка действительно её устраняет. «Подождать» означает, что причина реальна, но временна: это ограничение или блокировка, которые снимаются сами. Повторная отправка до этого момента ничего не даст и может продлить действие условия.
Почему большинство этих ошибок нельзя устранить повторной отправкой
Потому что платформа возвращает конкретные коды, а не общие ошибки. Неверный параметр, несуществующий шаблон, закрытое окно обмена сообщениями и получатель, отказавшийся от рассылки, известны уже в момент ответа. Поэтому Meta называет причину, а не возвращает расплывчатую ошибку.
- Проблема в запросе не исчезает со второй попытки.
- Проблема шаблона находится в самом шаблоне, и запрос не может её изменить.
- Проблема окна или отказа от рассылки связана с состоянием получателя, а не с вашим.
- Ограничение аккаунта является решением, а повторная отправка не является апелляцией.
Что записывать при появлении одной из этих ошибок
Достаточно данных, чтобы установить причину без воспроизведения ошибки. Именно это отличает исправление за пять минут от дня догадок.
- Полный ответ с ошибкой, включая идентификатор трассировки, который запрашивает поддержка Meta.
- Тело запроса в отправленном виде, а не в предполагаемом. Разница между ними обычно и есть ошибка.
- Идентификатор номера телефона, чтобы отличить проблему одного номера от проблемы всего аккаунта.
- Время, чтобы сопоставить ошибку с состоянием подключения в этот момент.
Коды, которые существуют только в Coexistence
Таких кодов два. Они сбивают с толку, потому что похожи на обычные ошибки отправки. 2593107 и 2593108 относятся к синхронизации истории чатов. На этом этапе при первом подключении номера копируются недавние разговоры из приложения WhatsApp Business.
Это не ошибки обмена сообщениями и не признак сбоя подключения. Если синхронизация превышает ограничение или выполняется вне разрешённого окна, номер остаётся подключённым и продолжает нормально отправлять сообщения, но истории копируется меньше ожидаемого. Если принять это за сломанное подключение, можно отключить номер и начать заново, потеряв ещё больше истории вместо её восстановления.
Часто задаваемые вопросы
Какие ошибки нужно повторять?
131016 и 131000, с экспоненциальной задержкой. 130429, 132015 и 133008 исчезают сами, если подождать. Все остальные ошибки предсказуемы.
Означает ли код ошибки, что мой номер отключён?
Обычно нет. Большинство этих ошибок связаны с запросом, шаблоном или получателем. Проблемы подключения отображаются как вебхуки аккаунта и рейтинга качества, а не как ошибки отправки.
Что такое идентификатор трассировки?
Это идентификатор в ответе с ошибкой, который помогает поддержке Meta найти конкретный запрос. Записывайте его при каждой ошибке: без него обращение нельзя обработать.
Одинаковы ли эти коды у всех провайдеров?
Да. Они приходят из Cloud API Meta, поэтому одинаковы у любого провайдера, подключившего номер. Провайдер может изменить только то, насколько понятно они до вас доходят.
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодВ течение 7 дней ничего не списывается. Отмена в любое время.