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

# Tratar erros do WhatsApp

> Distinga erros de solicitação da YCloud, erros de envio da Meta e falhas de entrega assíncronas.

Verifique tanto a resposta inicial da API quanto os webhooks `whatsapp.message.updated` posteriores. A aceitação pela YCloud ou pela Meta não confirma a entrega.

As tabelas abaixo restabelecem os casos de erro documentados. Elas não são uma lista exaustiva de erros que a Meta pode introduzir. Para detalhes atualizados do provedor, use a [referência de erros da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## A YCloud não conseguiu enviar mensagens

### `whatsappApiError` no corpo da resposta

Você pode receber um corpo de resposta de erro incluindo o campo `error.whatsappApiError` ao enviar mensagens do WhatsApp pela API da YCloud, normalmente a API Enviar uma mensagem do WhatsApp diretamente (`POST /v2/whatsapp/messages/sendDirectly`).

Aqui está um exemplo de resposta de erro com status HTTP `429` quando você envia mensagens em excesso para o mesmo número de telefone:

```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."
      }
    }
  }
}
```

Nesse caso, tentamos fazer a solicitação à WhatsApp Business API e recebemos uma resposta de erro. O `error.whatsappApiError` é incluído para ajudar você a identificar o motivo do erro.

### `whatsappApiError` no payload do webhook

Se você estiver usando a API Enfileirar uma mensagem do WhatsApp (`POST /v2/whatsapp/messages`), nunca receberá uma resposta de erro contendo `error.whatsappApiError`, pois enviamos suas mensagens para a WhatsApp Business API de forma assíncrona. Você pode obtê-la configurando um webhook para escutar eventos `whatsapp.message.updated`. Aqui está um exemplo do payload do 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"
  }
}
```

### códigos de erro retornados pela WhatsApp Business API

O `whatsappApiError` é exatamente o [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax). Listados abaixo estão alguns códigos de erro possíveis que podem ser retornados por meio da API da YCloud.

| Código | Descrição | Soluções possíveis | Status HTTP |
| - | - | - | - |
| `2`<br />API Service | Temporário devido a tempo de inatividade ou por estar sobrecarregado. | Verifique a página [Status da Plataforma WhatsApp Business](https://metastatus.com/whatsapp-business-api) para consultar informações sobre o status da API antes de tentar novamente. | `503`<br />Service Unavailable |
| `100`<br />Invalid parameter | A solicitação incluiu um ou mais parâmetros não suportados ou com erros ortográficos. Ou o número de telefone do destinatário não é um número de telefone do WhatsApp. | | `400`<br />Bad Request |
| `130429`<br />Rate limit hit | A taxa de transferência (throughput) de mensagens da Cloud API foi atingida. | O aplicativo atingiu o limite de taxa de transferência da API. Consulte [Taxa de transferência](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/#throughput). Tente novamente mais tarde ou reduza a frequência com que o aplicativo envia mensagens. | `429`<br />Too Many Requests |
| `131000`<br />Something went wrong | Falha ao enviar mensagem devido a um erro desconhecido. | Tente novamente. Se o erro persistir, entre em contato conosco para abrir um chamado no [Direct Support](https://business.facebook.com/direct-support). | `500`<br />Internal Server Error |
| `131008`<br />Required parameter is missing | A solicitação está sem um parâmetro obrigatório. | | `400`<br />Bad Request |
| `131026`<br />Message Undeliverable | Não foi possível entregar a mensagem. Os motivos podem incluir: <br /> <br />• O número de telefone do destinatário não é um número de telefone do WhatsApp.<br />• O destinatário não aceitou nossos novos Termos de Serviço e Política de Privacidade. <br />• O destinatário está usando um cliente do WhatsApp desatualizado.<br /> | Usando um método de comunicação diferente do WhatsApp, peça ao usuário do WhatsApp para:<br /> • Confirmar se ele consegue realmente enviar uma mensagem para o seu número de telefone comercial do WhatsApp.<br /> • Confirmar se ele aceitou nossos Termos de Serviço mais recentes (Configurações > Ajuda, ou Configurações > Informações do aplicativo solicitarão que ele aceite os termos/políticas mais recentes, caso ainda não o tenha feito)<br /> • Atualizar para a versão mais recente do cliente do WhatsApp. | `400`<br />Bad Request |
| `131031`<br />Account has been locked | A conta do WhatsApp Business associada ao aplicativo foi restrita ou desativada por violar uma política da plataforma, ou não foi possível verificar os dados incluídos na solicitação com os dados definidos na conta do WhatsApp Business (por exemplo, o PIN de confirmação em duas etapas incluído na solicitação está incorreto). | Consulte o documento [Cumprimento de Políticas](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) para saber mais sobre violações de políticas e como resolvê-las. | `403`<br />Forbidden |
| `131056`<br />Limite de taxa de par (Business Account, Consumer Account) atingido | Muitas mensagens enviadas do número de telefone do remetente para o mesmo número de telefone do destinatário em um curto período de tempo. | Aguarde e tente novamente a operação, caso pretenda enviar mensagens para o mesmo número de telefone. Você ainda pode enviar mensagens para um número de telefone diferente sem esperar. | `429`<br />Too Many Requests |
| `132000`<br />Incompatibilidade na contagem de parâmetros do modelo | O número de valores de parâmetros variáveis incluídos na solicitação não correspondeu ao número de parâmetros variáveis definidos no modelo. | Certifique-se de que a solicitação inclua todos os valores de parâmetros variáveis que foram definidos no modelo. | `400`<br />Bad Request |
| `132001`<br />O modelo não existe | O modelo não existe no idioma especificado ou ainda não foi aprovado. | Certifique-se de que seu modelo foi aprovado e de que o nome do modelo e o idioma (locale) estão corretos. | `400`<br />Bad Request |
| `132007`<br />Violação da política de caracteres de formatação do modelo | O conteúdo do modelo viola uma política do WhatsApp. | Consulte [Motivos de rejeição](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#rejection-reasons) para determinar os possíveis motivos da violação. | `400`<br />Bad Request |
| `132012`<br />Incompatibilidade no formato do parâmetro do modelo | Valores de parâmetros variáveis formatados incorretamente. | Os valores dos parâmetros variáveis incluídos na solicitação não estão usando o formato especificado no modelo. | `400`<br />Bad Request |
| `132015`<br />O modelo está pausado | O modelo está pausado devido à baixa qualidade, portanto, não pode ser enviado em uma mensagem de modelo. | Edite o modelo para melhorar sua qualidade e tente novamente assim que for aprovado. | `400`<br />Bad Request |
| `132016`<br />O modelo está desativado | O modelo foi pausado muitas vezes devido à baixa qualidade e agora está permanentemente desativado. | Crie um novo modelo com conteúdo diferente. | `400`<br />Bad Request |
| `133010`<br />Número de telefone não registrado | Número de telefone comercial não registrado na WhatsApp Business Platform. | Registre o número de telefone antes de tentar novamente. | `400`<br />Bad Request |
| `130472`<br />O número do usuário faz parte de um experimento | A mensagem não foi enviada como parte de um [experimento](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments). | Consulte [Experimento de mensagens de marketing](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments#marketing-message-experiment). | `400`<br />Bad Request |

### códigos de erro retornados pela API da YCloud

Esteja ciente de que `error.whatsappApiError` não é incluído quando os erros são detectados pela YCloud e não chegamos a chamar a WhatsApp Business API. Por exemplo, quando você fornece um número de telefone inválido e recebe a seguinte resposta de erro:

```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"
  }
}
```

O `error.code` é um dos [códigos de erro](/pt/api-reference/guides/api-fundamentals/handle-errors#error-codes) definidos pelo servidor da YCloud.

Abaixo estão listados alguns possíveis códigos de erro retornados pela API da YCloud:

| Código | Descrição | Status HTTP |
| :- | :- | :- |
| PARAM\_INVALID | Um ou mais parâmetros são inválidos. | `400`<br />Bad Request |
| PARAM\_MISSING | Um ou mais parâmetros estão ausentes. | `400`<br />Bad Request |
| BALANCE\_INSUFFICIENT | O saldo da conta é insuficiente. | `403`<br />Forbidden |
| WHATSAPP\_WABA\_UNAVAILABLE | A conta do WhatsApp Business não está disponível. | `403`<br />Forbidden |
| WHATSAPP\_PHONE\_NUMBER\_UNAVAILABLE | O número de telefone do WhatsApp Business não está disponível. | `403`<br />Forbidden |
| WHATSAPP\_TEMPLATE\_UNAVAILABLE | O modelo do WhatsApp está indisponível. | `403`Forbidden |
| UNAUTHORIZED | Não autorizado. Certifique-se de que está usando a Chave de API correta no cabeçalho 'X-API-Key'. | `401`<br />Unauthorized |

### Códigos de erro da YCloud transmitidos por webhooks

Se você estiver usando o endpoint Enqueue a WhatsApp message (`POST /v2/whatsapp/messages`), a mensagem pode falhar devido a um erro da YCloud. Ou seja, o `whatsappMessage.errorCode` no payload do webhook também pode transmitir um dos [Códigos de Erro da YCloud](/pt/api-reference/guides/api-fundamentals/handle-errors#error-codes), como `BALANCE_INSUFFICIENT`.

Aqui estão alguns erros possíveis:

| Código de Erro | Descrição | Soluções Possíveis |
| :- | :- | :- |
| `INTERNAL_SERVER_ERROR` | Temporário devido a tempo de inatividade ou sobrecarga. | Aguarde e tente a operação novamente.<br />Este erro pode ser causado por um timeout em nossa chamada para a WhatsApp Business API. |
| `BALANCE_INSUFFICIENT` | O saldo da sua conta é insuficiente. | Faça uma recarga. |
| `RECIPIENT_UNSUBSCRIBED` | O destinatário cancelou a inscrição. | Respeite a opção de cancelamento (opt-out) do usuário. Retome o envio de mensagens apenas depois que o usuário fornecer um consentimento válido novamente e seus registros de inscrição forem atualizados. |

## A Meta falhou ao enviar mensagens

Nem todos os códigos de erro listados na página de [Erros da WhatsApp Business Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax) são retornados por meio da API da YCloud. Mesmo que uma mensagem seja enviada com sucesso para a WhatsApp Business API, o envio ainda pode falhar. A Meta notifica a YCloud sobre esses erros via webhooks. Você deve [Configurar Webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks) escutando eventos de `whatsapp.message.updated` para receber essas notificações da YCloud. Aqui está um exemplo do payload do webhook para mensagens enviadas, mas que falharam no final:

```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"
  }
}
```

O `whatsappMessage.errorCode` transmite o código de [Erro da WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax).

### Códigos de erro da Meta transmitidos por webhooks

Listados abaixo estão alguns códigos de erro possíveis transmitidos pelos webhooks da YCloud, originados dos webhooks da Meta:

| Código | Descrição | Soluções Possíveis |
| - | - | - |
| `131000`<br />Algo deu errado | Falha ao enviar a mensagem devido a um erro desconhecido. | Tente novamente. Se o erro persistir, entre em contato conosco para abrir um tíquete no [Suporte Direto](https://business.facebook.com/direct-support). |
| `131026`<br />Mensagem não entregue | Não foi possível entregar a mensagem. Os motivos podem incluir: <br /> <br />• O número de telefone do destinatário não é um número de telefone do WhatsApp.<br />• O destinatário não aceitou nossos novos Termos de Serviço e Política de Privacidade. <br />• O destinatário está usando um cliente do WhatsApp desatualizado.<br /> | Usando um método de comunicação diferente do WhatsApp, peça ao usuário do WhatsApp para:<br /> • Confirmar que ele consegue enviar uma mensagem para o seu número de telefone comercial do WhatsApp.<br /> • Confirmar que ele aceitou nossos Termos de Serviço mais recentes (Configurações > Ajuda, ou Configurações > Informações do aplicativo solicitarão que ele aceite os termos/políticas mais recentes, se ainda não o tiver feito)<br /> • Atualizar para a versão mais recente do aplicativo WhatsApp. |
| `131031`<br />A conta foi bloqueada | A conta do WhatsApp Business associada ao aplicativo foi restrita ou desativada por violar uma política da plataforma, ou não conseguimos verificar os dados incluídos na solicitação em relação aos dados definidos na conta do WhatsApp Business (por exemplo, o PIN de confirmação em duas etapas incluído na solicitação está incorreto). | Consulte o documento de [Aplicação de Políticas](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) para saber mais sobre violações de políticas e como resolvê-las. |
| `131047`<br />Mensagem de reengajamento | Mais de 24 horas se passaram desde a última vez que o destinatário respondeu ao número do remetente. | Em vez disso, envie ao destinatário uma mensagem iniciada pela empresa usando um modelo de mensagem. |
| `131048`<br />Limite de taxa de spam atingido | Falha ao enviar a mensagem porque há restrições quanto ao número de mensagens que podem ser enviadas a partir deste número de telefone. Isso pode ocorrer porque muitas mensagens anteriores foram bloqueadas ou sinalizadas como spam. | Verifique seu status de qualidade no Gerenciador do WhatsApp e consulte a documentação de [Limites de taxa baseados em qualidade](https://developers.facebook.com/docs/whatsapp/messaging-limits#quality-rating-and-messaging-limits) para obter mais informações. |
| `131049`<br /> | Esta mensagem não foi entregue para manter o engajamento saudável do ecossistema. | Não tente novamente de imediato se você receber este código de erro e suspeitar que seja devido ao limite. Em vez disso, tente novamente em intervalos de tempo cada vez maiores até que a mensagem seja entregue, já que o limite pode permanecer ativo por períodos variados de tempo.<br />Consulte [Limites de modelos de mensagem de marketing por usuário](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits) para obter informações adicionais. |
| `131053`<br />Erro de upload de mídia | Não foi possível fazer upload da mídia usada na mensagem. | Não conseguimos fazer o upload da mídia por um ou mais motivos, como um [tipo de mídia não suportado](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
| `131050`<br />Mensagem não entregue | Não foi possível entregar a mensagem. Este destinatário optou por deixar de receber mensagens de marketing da sua empresa no WhatsApp | |


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