> ## 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

> Различайте ошибки запросов YCloud, ошибки отправки со стороны Meta и асинхронные сбои доставки.

Проверяйте как первоначальный ответ API, так и последующие Webhook `whatsapp.message.updated`.
Принятие запроса сервисом YCloud или Meta не подтверждает фактическую доставку.

Приведенные ниже таблицы содержат задокументированные случаи ошибок. Они не представляют собой исчерпывающий
список ошибок, которые могут возникать на стороне Meta. Актуальные сведения от провайдера доступны в
[справочнике по ошибкам Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## Сбой отправки сообщений со стороны YCloud

### `whatsappApiError` в теле ответа

Вы можете получить тело ответа с ошибкой, содержащее поле `error.whatsappApiError`, при отправке сообщений WhatsApp через YCloud API, как правило, при использовании API прямой отправки сообщений WhatsApp (`POST /v2/whatsapp/messages/sendDirectly`).

Вот пример ответа с ошибкой и HTTP-статусом `429`, когда на один и тот же номер телефона отправляется слишком много сообщений:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 429,
    "code": "TOO_MANY_REQUESTS",
    "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "target": "whatsappApiError",
    "docUrl": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes",
    "requestId": "req_1KjtKI80IKoaJNa6n6p",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    }
  }
}
```

В этом случае мы попытались отправить запрос к WhatsApp Business API и получили ответ с ошибкой. Поле `error.whatsappApiError` включено, чтобы помочь вам определить причину ошибки.

### `whatsappApiError` в полезной нагрузке Webhook

Если вы используете API постановки сообщений WhatsApp в очередь (`POST /v2/whatsapp/messages`), вы никогда не получите ответ с ошибкой, содержащий `error.whatsappApiError`, поскольку мы отправляем ваши сообщения в WhatsApp Business API асинхронно. Вы можете получить эти данные, настроив Webhook для прослушивания событий `whatsapp.message.updated`. Вот пример полезной нагрузки Webhook:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131056",
    "errorMessage": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    },
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

### коды ошибок, возвращаемые WhatsApp Business API

Поле `whatsappApiError` в точности соответствует [ошибке WhatsApp Business Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax). Ниже перечислены некоторые возможные коды ошибок, которые могут возвращаться через YCloud API.

| Код | Описание | Возможные решения | HTTP-статус |
| - | - | - | - |
| `2`<br />API Service | Временная ошибка из-за простоя или перегрузки сервиса. | Проверьте страницу [WhatsApp Business Platform Status](https://metastatus.com/whatsapp-business-api), чтобы узнать статус API, прежде чем повторять попытку. | `503`<br />Service Unavailable |
| `100`<br />Invalid parameter | Запрос содержит один или несколько неподдерживаемых параметров либо параметров с опечатками. Или номер телефона получателя не зарегистрирован в WhatsApp. | | `400`<br />Bad Request |
| `130429`<br />Rate limit hit | Достигнута максимальная пропускная способность сообщений Cloud API. | Приложение исчерпало лимит пропускной способности API. См. [Throughput](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/#throughput). Повторите попытку позже или уменьшите частоту отправки сообщений приложением. | `429`<br />Too Many Requests |
| `131000`<br />Something went wrong | Не удалось отправить сообщение из-за неизвестной ошибки. | Повторите попытку. Если ошибка повторяется, свяжитесь с нами, чтобы открыть заявку в [Direct Support](https://business.facebook.com/direct-support). | `500`<br />Internal Server Error |
| `131008`<br />Required parameter is missing | В запросе отсутствует обязательный параметр. | | `400`<br />Bad Request |
| `131026`<br />Message Undeliverable | Невозможно доставить сообщение. Возможные причины: <br /> <br />• Номер телефона получателя не зарегистрирован в WhatsApp.<br />• Получатель не принял новые Условия предоставления услуг и Политику конфиденциальности. <br />• Получатель использует устаревший клиент WhatsApp.<br /> | Используя способ связи, отличный от WhatsApp, попросите пользователя WhatsApp:<br /> • Убедиться, что он действительно может отправить сообщение на ваш рабочий номер телефона WhatsApp.<br /> • Подтвердить согласие с актуальными Условиями предоставления услуг (в разделах «Настройки» > «Помощь» или «Настройки» > «О приложении» появится предложение принять новые условия/политики, если это еще не сделано).<br /> • Обновить клиент WhatsApp до последней версии. | `400`<br />Bad Request |
| `131031`<br />Account has been locked | WhatsApp Business Account, связанный с приложением, заблокирован или его действие ограничено из-за нарушения политик платформы, либо нам не удалось сопоставить данные из запроса со значениями в WhatsApp Business Account (например, в запросе указан неверный PIN-код двухшаговой проверки). | См. документ [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/), чтобы узнать о нарушениях политик и способах их устранения. | `403`<br />Forbidden |
| `131056`<br />Превышен лимит частоты запросов для пары (Business Account, Consumer Account) | Слишком много сообщений отправлено с номера телефона отправителя на один и тот же номер телефона получателя за короткий промежуток времени. | Подождите и повторите попытку, если вы хотите отправить сообщения на тот же номер телефона. Вы по-прежнему можете отправлять сообщения на другой номер телефона без ожидания. | `429`<br />Too Many Requests |
| `132000`<br />Несовпадение количества параметров шаблона | Количество значений переменных параметров в запросе не совпадает с количеством переменных параметров, определенных в шаблоне. | Убедитесь, что запрос содержит все значения переменных параметров, заданные в шаблоне. | `400`<br />Bad Request |
| `132001`<br />Шаблон не существует | Шаблон не существует для указанного языка или шаблон еще не был одобрен. | Убедитесь, что шаблон одобрен, а имя шаблона и языковая локаль указаны правильно. | `400`<br />Bad Request |
| `132007`<br />Нарушение политики форматирования символов шаблона | Содержимое шаблона нарушает политику WhatsApp. | См. [Причины отклонения](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#rejection-reasons), чтобы определить возможные причины нарушения. | `400`<br />Bad Request |
| `132012`<br />Несовпадение формата параметров шаблона | Значения переменных параметров отформатированы некорректно. | Значения переменных параметров в запросе не соответствуют формату, указанному в шаблоне. | `400`<br />Bad Request |
| `132015`<br />Шаблон приостановлен | Шаблон приостановлен из-за низкого качества и не может быть отправлен в шаблонном сообщении. | Отредактируйте шаблон, чтобы повысить его качество, и повторите попытку после его одобрения. | `400`<br />Bad Request |
| `132016`<br />Шаблон отключен | Шаблон слишком много раз приостанавливался из-за низкого качества и теперь отключен навсегда. | Создайте новый шаблон с другим содержимым. | `400`<br />Bad Request |
| `133010`<br />Номер телефона не зарегистрирован | Бизнес-номер телефона не зарегистрирован на платформе WhatsApp Business Platform. | Зарегистрируйте номер телефона перед повторной попыткой. | `400`<br />Bad Request |
| `130472`<br />Номер пользователя участвует в эксперименте | Сообщение не было отправлено в рамках [эксперимента](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments). | См. [Эксперимент с маркетинговыми сообщениями](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments#marketing-message-experiment). | `400`<br />Bad Request |

### коды ошибок, возвращаемые YCloud API

Обратите внимание, что `error.whatsappApiError` не включается, если ошибки были обнаружены YCloud и запрос к WhatsApp Business API не выполнялся. Например, если вы укажете недействительный номер телефона, то получите следующий ответ с ошибкой:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 400,
    "code": "PARAM_INVALID",
    "message": "Invalid E.164 phone number: +001",
    "target": "to",
    "docUrl": "https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/handle-errors#error-codes",
    "requestId": "req_69UpMOaMHFrBMGZexYvUDw"
  }
}
```

Значение `error.code` представляет собой один из определяемых сервером YCloud [кодов ошибок](/ru/api-reference/guides/api-fundamentals/handle-errors#error-codes).

Ниже приведены некоторые возможные коды ошибок, возвращаемые YCloud API:

| Код | Описание | HTTP-статус |
| :- | :- | :- |
| PARAM\_INVALID | Один или несколько параметров недействительны. | `400`<br />Bad Request |
| PARAM\_MISSING | Один или несколько параметров отсутствуют. | `400`<br />Bad Request |
| BALANCE\_INSUFFICIENT | Недостаточно средств на балансе аккаунта. | `403`<br />Forbidden |
| WHATSAPP\_WABA\_UNAVAILABLE | WhatsApp Business Account недоступен. | `403`<br />Forbidden |
| WHATSAPP\_PHONE\_NUMBER\_UNAVAILABLE | Бизнес-номер телефона WhatsApp недоступен. | `403`<br />Forbidden |
| WHATSAPP\_TEMPLATE\_UNAVAILABLE | Шаблон WhatsApp недоступен. | `403`Forbidden |
| UNAUTHORIZED | Не авторизовано. Убедитесь, что вы используете правильный API Key в заголовке 'X-API-Key'. | `401`<br />Unauthorized |

### Коды ошибок YCloud, передаваемые через Webhook

Если вы используете эндпоинт постановки сообщения WhatsApp в очередь (`POST /v2/whatsapp/messages`), доставка может завершиться ошибкой YCloud. То есть `whatsappMessage.errorCode` в теле Webhook также может передавать один из [кодов ошибок YCloud](/ru/api-reference/guides/api-fundamentals/handle-errors#error-codes), например `BALANCE_INSUFFICIENT`.

Вот некоторые возможные ошибки:

| Код ошибки | Описание | Возможные решения |
| :- | :- | :- |
| `INTERNAL_SERVER_ERROR` | Временная ошибка из-за простоя или перегрузки. | Подождите и повторите операцию.<br />Эта ошибка может быть вызвана тайм-аутом при обращении к WhatsApp Business API. |
| `BALANCE_INSUFFICIENT` | Недостаточный баланс аккаунта. | Пополните баланс. |
| `RECIPIENT_UNSUBSCRIBED` | Получатель отписался. | Уважайте отказ пользователя от сообщений. Возобновляйте отправку только после того, как пользователь снова предоставит действительное согласие, а ваши записи о подписке будут обновлены. |

## Сбой отправки сообщений со стороны Meta

Не все коды ошибок, перечисленные на странице [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax), возвращаются через YCloud API. Даже если сообщение успешно передано в WhatsApp Business API, его отправка все равно может завершиться ошибкой. Meta уведомляет YCloud об этих ошибках через Webhook. Вам следует [настроить Webhook](/ru/api-reference/guides/api-fundamentals/configure-webhooks) для прослушивания событий `whatsapp.message.updated`, чтобы получать эти уведомления от YCloud. Ниже приведен пример полезной нагрузки Webhook для сообщений, которые были отправлены, но в итоге завершились ошибкой:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131048",
    "errorMessage": "Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam.",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

`whatsappMessage.errorCode` передает код [ошибки WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax).

### Коды ошибок Meta, передаваемые через Webhook

Ниже перечислены некоторые возможные коды ошибок, передаваемые через Webhook YCloud и полученные от Webhook Meta:

| Код | Описание | Возможные решения |
| - | - | - |
| `131000`<br />Something went wrong | Не удалось отправить сообщение из-за неизвестной ошибки. | Повторите попытку. Если ошибка повторяется, свяжитесь с нами, чтобы открыть обращение в [Direct Support](https://business.facebook.com/direct-support). |
| `131026`<br />Message Undeliverable | Не удалось доставить сообщение. Причины могут включать: <br /> <br />• Номер телефона получателя не зарегистрирован в WhatsApp.<br />• Получатель не принял наши новые Условия использования и Политику конфиденциальности. <br />• Получатель использует устаревший клиент WhatsApp.<br /> | Используя способ связи вне WhatsApp, попросите пользователя WhatsApp:<br /> • Подтвердить, что он действительно может отправить сообщение на ваш рабочий номер телефона WhatsApp.<br /> • Подтвердить, что он принял наши актуальные Условия использования («Настройки» > «Справка» или «Настройки» > «Информация о приложении» предложат принять актуальные условия/политики, если это еще не сделано).<br /> • Обновить клиент WhatsApp до последней версии. |
| `131031`<br />Account has been locked | WhatsApp Business Account, связанный с приложением, был ограничен или заблокирован за нарушение правил платформы, либо нам не удалось сопоставить данные, указанные в запросе, с данными в WhatsApp Business Account (например, неверно указан двухшаговый PIN-код в запросе). | См. документ [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/), чтобы узнать о нарушениях политик и способах их устранения. |
| `131047`<br />Re-engagement message | Прошло более 24 часов с момента последнего ответа получателя на номер отправителя. | Отправьте получателю сообщение, инициированное компанией, используя шаблон сообщения. |
| `131048`<br />Превышен лимит спама | Не удалось отправить сообщение, так как действуют ограничения на количество сообщений, отправляемых с этого номера телефона. Возможно, слишком много предыдущих сообщений были заблокированы или помечены как спам. | Проверьте статус качества в WhatsApp Manager и ознакомьтесь с документацией [Лимиты на основе качества](https://developers.facebook.com/docs/whatsapp/messaging-limits#quality-rating-and-messaging-limits) для получения дополнительной информации. |
| `131049`<br /> | Это сообщение не было доставлено для поддержания здорового взаимодействия в экосистеме. | Не повторяйте попытку сразу же, если вы получили этот код ошибки и предполагаете, что дело в лимите. Вместо этого повторяйте попытки с увеличивающимися интервалами времени, пока сообщение не будет доставлено, поскольку лимит может действовать в течение разного времени.<br />См. дополнительную информацию в разделе [Лимиты на маркетинговые шаблоны сообщений на пользователя](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits). |
| `131053`<br />Ошибка загрузки медиа | Не удалось загрузить медиафайл, используемый в сообщении. | Нам не удалось загрузить медиафайл по одной или нескольким причинам, таким как [неподдерживаемый тип медиа](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
| `131050`<br />Сообщение не доставлено | Не удалось доставить сообщение. Этот получатель решил отказаться от получения маркетинговых сообщений в WhatsApp от вашей компании | |


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