> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Коды ошибок WhatsApp

> Справочник кодов ошибок сообщений WhatsApp и способы решения проблем с недоставленными сообщениями, отправленными через YCloud.

Отслеживайте как ответы API, так и вебхуки `whatsapp.message.updated`. Ошибка при отправке сообщения может произойти, когда YCloud проверяет ваш запрос, когда отправляет сообщение в WhatsApp или уже после того, как WhatsApp принял сообщение к доставке. Используйте возвращенный код и сведения об ошибке, чтобы определить причину перед повторной попыткой.

## Где найти код ошибки

| Где возникает ошибка | Где посмотреть ошибку |
| - | - |
| YCloud отклоняет запрос до отправки в WhatsApp | Проверьте `error.code`, `error.message` и `error.target` в ответе API. Вышестоящий `whatsappApiError` отсутствует. |
| WhatsApp отклоняет синхронную отправку через `POST /v2/whatsapp/messages/sendDirectly` | Проверьте поля ошибок YCloud вместе с `error.whatsappApiError`, если оно присутствует. Поле `code` определяет вышестоящую ошибку WhatsApp. |
| Сообщение из очереди не отправлено через `POST /v2/whatsapp/messages` | Проверьте `whatsappMessage.status`, `whatsappMessage.errorCode` и `whatsappMessage.errorMessage` в вебхуке `whatsapp.message.updated`. Проверьте `whatsappMessage.whatsappApiError`, если оно присутствует. |
| WhatsApp принимает сообщение, но позже не может его доставить | Проверьте `whatsappMessage.errorCode` и `whatsappMessage.errorMessage` в вебхуке `whatsapp.message.updated` со значением `whatsappMessage.status: "failed"`. Наличие объекта `whatsappApiError` для обработки ошибки не обязательно. |
| Входящее сообщение содержит ошибку неподдерживаемого контента или медиафайла | В вебхуке `whatsapp.inbound_message.received` проверьте `whatsappInboundMessage.errors[]`, если оно присутствует. Каждая запись может содержать `code`, `message` и `error_data.details`. |

Эндпоинт с очередью возвращает ответ до того, как сообщение отправляется в WhatsApp, поэтому его первоначальный ответ не может сообщить о последующей ошибке отправки. Синхронный эндпоинт сообщает результат отправки, но сбой с сообщением всё равно может произойти позже. Принятый запрос не подтверждает доставку; отслеживайте вебхуки для обоих эндпоинтов.

### Чтение кода и сведений об ошибке

Разделяйте ошибку запроса YCloud и вышестоящую ошибку WhatsApp. Например, синхронный ответ может содержать `error.code: "TOO_MANY_REQUESTS"` и `error.whatsappApiError.code: "131056"`. Первое описывает ответ API; второе указывает на ограничение частоты сообщений между отправителем и получателем.

В вебхуке о сбое доставки сообщения поле `whatsappMessage.errorCode` может содержать как код YCloud, такой как `BALANCE_INSUFFICIENT`, так и код WhatsApp, например `131048`. Сохраняйте его как строку.

Если поле `whatsappApiError` доступно, проверьте его поля `code` и `error_data` для определения конкретной причины. Для ошибок API сообщений поле `error_data` может содержать свойство `details`; для ошибок API шаблонов оно может быть строкой. Сопоставляйте коды, а не заголовки ошибок или текст сообщений, так как они могут меняться.

Приведенные ниже числовые коды относятся к вышестоящим ошибкам WhatsApp. Информацию о кодах YCloud, таких как `UNAUTHORIZED`, `PARAM_INVALID` или `BALANCE_INSUFFICIENT`, см. в разделе [Обработка ошибок](/ru/api-reference/guides/api-fundamentals/handle-errors).

Сведения об эндпоинтах отправки см. в разделе [Отправка сообщения WhatsApp](/ru/api-reference/guides/whatsapp-platform/send-whatsapp-message), а информацию о получении обновлений статуса сообщений — в разделе [Настройка вебхуков](/ru/api-reference/guides/api-fundamentals/configure-webhooks).

## Лимиты на отправку и ограничения по качеству

| Код | Значение | Что делать |
| - | - | - |
| `80007` | WhatsApp Business Account исчерпал лимит вызовов API. | Сократите количество запросов для затронутого WABA и повторите попытку позже с экспоненциальной задержкой. |
| `130429` | Превышена пропускная способность отправки сообщений. | Уменьшите частоту отправки для соответствующего бизнес-номера телефона и распределяйте отправку во времени. |
| `131048` | Отправка ограничена из-за сигналов о спаме или низком качестве. | Приостановите затронутые отправки. Проверьте показатель качества номера телефона, согласие аудитории и последние негативные отзывы перед возобновлением. |
| `131056` | С одного бизнес-номера одному и тому же получателю было отправлено слишком много сообщений за короткий период времени. | Подождите перед повторной попыткой отправки этой паре «отправитель — получатель». Данный конкретный лимит не блокирует отправку другим получателям. |
| `131064` | Нарушения классификации шаблонов привели к ограничению обмена сообщениями. | Проверьте категории шаблонов и исправьте некорректно классифицированный контент. Ограничение распространяется на шаблонные сообщения и сообщения Direct Send и снимается после окончания периода применения мер. |

Информацию об ограничениях качества и лимитах на уровне получателей см. в разделе [Контроль качества и доставки](/ru/documentation/whatsapp-business-platform/pricing-limits-and-quality/quality-and-delivery-controls).

## Ошибки получателя и доставки

| Код | Значение | Что делать |
| - | - | - |
| `130403` | Ваша компания заблокировала этого получателя в WhatsApp. | Не повторяйте попытку, пока блокировка активна. Проверьте причину блокировки, прежде чем решать, следует ли возобновлять общение. |
| `130472` | WhatsApp задержал сообщение в рамках эксперимента на платформе. | Не отправляйте одно и то же сообщение повторно несколько раз. Используйте другой согласованный канал связи, если информация срочная. |
| `131021` | Номера телефонов отправителя и получателя совпадают. | Отправьте сообщение на другой номер получателя. |
| `131026` | Не удалось доставить сообщение. Возможные причины: номер не зарегистрирован в WhatsApp, условия использования WhatsApp не приняты или используется устаревшая версия приложения. | Через другой согласованный канал попросите получателя убедиться, что он может писать вашей компании, принять актуальные условия использования WhatsApp и обновить приложение WhatsApp. Сам по себе код ошибки не указывает на одну точную причину. |
| `131047` | 24-часовое окно клиентской поддержки истекло. | Отправьте подходящий одобренный шаблон или дождитесь нового сообщения от клиента, прежде чем отправлять ответ в свободной форме. |
| `131049` | WhatsApp задержал сообщение для защиты вовлеченности получателя. | Избегайте немедленных повторных попыток. Если вы предполагаете лимит на маркетинговые сообщения для получателя, подождите не менее 24 часов перед повторной отправкой. Сначала проверьте согласие и актуальность; ожидание не гарантирует доставку. |
| `131050` | Получатель заблокировал получение маркетинговых сообщений от вашей компании в WhatsApp. | Прекратите маркетинговые отправки этому получателю. Не повторяйте попытку отправки недоставленного маркетингового сообщения. |

## Ошибки шаблонов и сообщений Flow

Перед повторной попыткой проверьте точное название шаблона, язык, статус и определения компонентов в YCloud.

| Код | Значение | Что делать |
| - | - | - |
| `132000` | Количество переданных параметров шаблона не соответствует шаблону. | Укажите необходимое количество значений для каждого компонента. |
| `132001` | Шаблон отсутствует на запрошенном языке или не одобрен. | Проверьте имя, код языка, WABA и статус одобрения. |
| `132005` | Текст шаблона превышает допустимую длину. | Проверьте шаблон и переданные текстовые значения на соответствие действующим ограничениям длины. |
| `132007` | Содержимое шаблона нарушает правила WhatsApp. | Изучите указанное нарушение и исправьте содержимое перед повторной отправкой. |
| `132012` | Форматы параметров шаблона не соответствуют определению. | Проверьте каждый компонент и тип параметра, включая медиазаголовки и кнопки. |
| `132015` | Шаблон приостановлен из-за низкого качества. | Прекратите отправки с его использованием. Улучшите его содержимое и возобновите работу только после того, как шаблон будет одобрен и станет доступен для использования. |
| `132016` | Шаблон окончательно отключен после неоднократных приостановок из-за качества. | Создайте замену с другим содержимым и устраните проблему с качеством перед отправкой. |
| `132068` | Flow, используемый в сообщении, заблокирован. | Проверьте статус Flow и устраните обнаруженную проблему перед его повторным использованием. |
| `132069` | Для Flow включено ограничение частоты (throttled), и достигнут лимит на отправку. | Проверьте состояние Flow и недавние отправки. Устраните проблему и подождите перед повторной попыткой. |

См. [Управление шаблонами WhatsApp](/ru/api-reference/guides/whatsapp-platform/manage-whatsapp-templates) и [Управление WhatsApp Flows](/ru/api-reference/guides/whatsapp-platform/manage-whatsapp-flows).

## Параметры сообщений и медиафайлы

| Код | Значение | Что делать |
| - | - | - |
| `100` | Запрос содержит неподдерживаемый или недопустимый параметр. | Ознакомьтесь с возвращенными подробностями и исправьте соответствующее поле, сверяясь со справочником эндпоинтов YCloud. |
| `131008` | Отсутствует обязательный параметр. | Добавьте поле или компонент, указанный в ошибке. |
| `131009` | Недопустимое значение параметра. | Исправьте значение, формат или длину, указанные в описании ошибки. |
| `131051` | Тип сообщения не поддерживается. | Для исходящих сообщений используйте поддерживаемый тип сообщений YCloud. Для входящих сообщений обработайте событие о неподдерживаемом типе, не рассчитывая на наличие стандартного содержимого сообщения. |
| `131052` | WhatsApp не удалось загрузить медиафайл, отправленный пользователем. | Изучите подробности ошибки входящего сообщения. При необходимости попросите пользователя отправить файл по другому согласованному каналу связи. |
| `131053` | Не удалось загрузить медиафайл, используемый в исходящем сообщении. | Проверьте фактический формат файла, MIME-тип, размер и доступность. Исправьте файл или URL перед повторной попыткой. |
| `135000` | WhatsApp сообщил о неуточненной ошибке в параметрах запроса. | Сверьте запрос со схемой YCloud API и сохраните возвращенные подробности ошибки. |

См. [Отправка сообщения WhatsApp](/ru/api-reference/guides/whatsapp-platform/send-whatsapp-message) и [Загрузка медиафайлов WhatsApp](/ru/api-reference/guides/whatsapp-platform/upload-whatsapp-media).

## Аккаунт, номер телефона и биллинг

| Код | Значение | Что делать |
| - | - | - |
| `368`, `131031` | Аккаунт WABA ограничен или заблокирован. Для `131031` проблема также может быть связана с данными верификации аккаунта. | Проверьте статус аккаунта и точные сведения об ошибке. |
| `130497` | Аккаунт WABA не может отправлять сообщения пользователям в определенных странах. | Проверьте направление и ограничения для вашей категории бизнеса. Не повторяйте попытку для неподдерживаемого направления без изменений. |
| `131042` | WhatsApp сообщил о проблеме с платежами или биллингом аккаунта. | Проверьте платежные настройки и статус биллинга WABA. Это не связано с балансом в `BALANCE_INSUFFICIENT` YCloud; простое пополнение баланса может не решить проблему. |
| `131045`, `133010` | Номер телефона компании не зарегистрирован или возникла проблема с его регистрацией. | Проверьте подключение номера и статус его регистрации в YCloud. |
| `131057` | Аккаунт временно находится в режиме технического обслуживания. | Дождитесь завершения обслуживания и повторите попытку с задержкой. |

## Ошибки маркетинговых сообщений

Эти ошибки могут возникать, когда YCloud отправляет сообщение через Meta Marketing Messages API. Используйте возвращенные подробности, чтобы различить проблемы с шаблонами, синхронизацией и маршрутизацией.

| Код | Значение | Что делать |
| - | - | - |
| `131055`, `134100` | Вышестоящий маркетинговый маршрут принимает только маркетинговые шаблоны. | Убедитесь, что для отправляемого сообщения используется шаблон `MARKETING`. Служебные шаблоны и шаблоны аутентификации требуют другого маршрута отправки. |
| `131063` | Маркетинговые шаблоны отключены на маршруте Cloud API для этого аккаунта. | Проверьте маршрут отправки маркетинговых сообщений и конфигурацию аккаунта. |
| `134101` | Маркетинговый шаблон все еще синхронизируется. | Подождите 10 минут перед повторной попыткой использования вновь созданного шаблона. |
| `134102` | Шаблон недоступен, поскольку синхронизация или проверка соответствия аккаунта требованиям еще не завершены. | Проверьте соответствие аккаунта требованиям и завершение синхронизации шаблонов. |
| `132018` | Сбой валидации параметров шаблона. | Исправьте параметры, указанные в ошибке, и повторите отправку только после успешной валидации. |

Для этого маршрута `100` может означать, что сообщение должно быть шаблонным, а `131009` может указывать на недопустимые параметры или незавершенную синхронизацию шаблона. Используйте возвращенные подробности, чтобы определить точную причину. В случае незавершенной синхронизации подождите 10 минут перед повторной попыткой.

## Временные ошибки сервиса

| Код | Значение | Что делать |
| - | - | - |
| `1` | Некорректный запрос или ошибка вышестоящего сервера. | Сначала проверьте запрос. Если он корректен, проверьте наличие временных неполадок в работе сервиса. |
| `2`, `131016` | Вышестоящий сервис временно недоступен или перегружен. | Проверьте статус [WhatsApp Business Platform](https://metastatus.com/whatsapp-business-api) и повторите временные сбои с ограниченным увеличением интервалов. |
| `131000` | Неуточненный сбой WhatsApp. | Проверьте статус сервиса и возвращенные подробности. Используйте повторные попытки с ограничением количества только при необходимости. |

## Повторные попытки и эскалация

* Перед повторной попыткой исправьте некорректные параметры, статус шаблона, ограничения аккаунта и проблемы с медиафайлами.
* Учитывайте отказы получателей от рассылок и блокировки. Не повторяйте попытки отправки при таких сбоях автоматически.
* Для временных сбоев используйте экспоненциальную задержку, джиттер и ограничение максимального количества попыток. Соблюдайте период ожидания, указанный выше или в ответе.
* Перед повторной отправкой после таймаута или неоднозначного ответа сверьте статус сообщения во избежание дублирования. Поле `externalId` служит для корреляции; не предполагайте, что оно обеспечивает дедупликацию отправок.

Если ошибка сохраняется после выполнения указанных выше проверок или вам требуется помощь с биллингом аккаунта, проверкой соответствия требованиям или настройкой маршрутизации отправки, свяжитесь со [службой поддержки YCloud](https://www.ycloud.com/console/#/app/getStarted). Укажите время сбоя и часовой пояс, конечную точку (эндпоинт), точный код ошибки и детали, `requestId` YCloud, `id` сообщения, а также `wamid` или `fbtrace_id` (при наличии). Удалите API-ключи и ненужные персональные данные.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.