Código de erro do WhatsApp

Monitore a resposta da API e os webhooks do whatsapp.message.updated. Uma mensagem pode falhar quando o YCloud valida sua solicitação, quando envia a mensagem para o WhatsApp ou depois que o WhatsApp aceita a mensagem para entrega. Use o código e os detalhes retornados para identificar a causa antes de tentar novamente.

Encontrar o código de erro

Onde a falha ocorre	Onde ler o erro
O YCloud rejeita a solicitação antes de enviá-la para o WhatsApp	Leia `error.code`, `error.message` e `error.target` na resposta da API. Nenhum `whatsappApiError` upstream está disponível.
O WhatsApp rejeita um envio síncrono por meio de `POST /v2/whatsapp/messages/sendDirectly`	Leia os campos de erro do YCloud junto com `error.whatsappApiError`, quando presente. Seu `code` identifica o erro upstream do WhatsApp.
Uma mensagem na fila falha durante o envio por meio de `POST /v2/whatsapp/messages`	Leia `whatsappMessage.status`, `whatsappMessage.errorCode` e `whatsappMessage.errorMessage` no webhook `whatsapp.message.updated`. Inspecione `whatsappMessage.whatsappApiError` quando presente.
O WhatsApp aceita a mensagem, mas posteriormente não consegue entregá-la	Leia `whatsappMessage.errorCode` e `whatsappMessage.errorMessage` em um webhook `whatsapp.message.updated` com `whatsappMessage.status: "failed"`. Não exija um objeto `whatsappApiError` para processar a falha.
Uma mensagem de entrada contém um erro de mídia ou conteúdo não suportado	No webhook `whatsapp.inbound_message.received`, inspecione `whatsappInboundMessage.errors[]` quando presente. Cada entrada pode incluir `code`, `message` e `error_data.details`.

O endpoint com enfileiramento retorna antes que a mensagem seja enviada para o WhatsApp, portanto sua resposta inicial não pode relatar uma falha de envio posterior. O endpoint síncrono relata o resultado do envio, mas a mensagem ainda pode falhar posteriormente. Uma solicitação aceita não confirma a entrega; monitore os webhooks para ambos os endpoints.

Ler o código e os detalhes

Mantenha o erro de solicitação do YCloud e o erro upstream do WhatsApp separados. Por exemplo, uma resposta síncrona pode conter error.code: "TOO_MANY_REQUESTS" e error.whatsappApiError.code: "131056". O primeiro descreve a resposta da API; o segundo identifica o limite de taxa de remetente–destinatário. Para um webhook de mensagem com falha, whatsappMessage.errorCode pode conter um código do YCloud como BALANCE_INSUFFICIENT ou um código do WhatsApp como 131048. Preserve-o como string. Quando whatsappApiError estiver disponível, inspecione seus code e error_data para identificar a causa específica. Para erros da API de mensagens, error_data pode conter uma propriedade details; para erros da API de modelos, ele pode ser uma string. Faça a correspondência por códigos em vez de títulos de erro ou texto de mensagem, que podem mudar. Os códigos numéricos abaixo descrevem falhas upstream do WhatsApp. Para códigos do YCloud como UNAUTHORIZED, PARAM_INVALID ou BALANCE_INSUFFICIENT, consulte Tratar erros. Consulte Enviar uma mensagem do WhatsApp para obter os endpoints de envio e Configurar webhooks para receber atualizações de status de mensagens.

Limites de envio e restrições de qualidade

Código	Significado	O que fazer
`80007`	A conta do WhatsApp Business atingiu o limite de chamadas de API.	Reduza as solicitações da WABA afetada e tente novamente mais tarde com backoff.
`130429`	A taxa de transferência de mensagens foi excedida.	Reduza a taxa de envio para o número de telefone comercial afetado e distribua os envios ao longo do tempo.
`131048`	O envio está restrito devido a sinais de spam ou qualidade.	Pause os envios afetados. Revise a qualidade do número de telefone, o consentimento do público e os feedbacks negativos recentes antes de retomar.
`131056`	Muitas mensagens foram enviadas de um número comercial para o mesmo destinatário em um curto período.	Aguarde antes de tentar novamente para esse par remetente–destinatário. Esse limite específico não impede envios para outros destinatários.
`131064`	Violações de classificação de modelos causaram uma restrição no envio de mensagens.	Revise as categorias de modelo e corrija o conteúdo classificado incorretamente. A restrição se aplica a modelos e mensagens de Direct Send e é suspensa após o período de aplicação.

Consulte Controles de qualidade e entrega para saber mais sobre restrições de qualidade e de destinatário.

Erros de destinatário e de entrega

Código	Significado	O que fazer
`130403`	Sua empresa bloqueou o destinatário no WhatsApp.	Não tente novamente enquanto o bloqueio permanecer. Revise o bloqueio antes de decidir se a comunicação deve ser retomada.
`130472`	O WhatsApp reteve a mensagem como parte de um experimento da plataforma.	Não reenvie repetidamente a mesma mensagem. Use outro canal de comunicação acordado se a informação for urgente.
`131021`	Os números de telefone do remetente e do destinatário são os mesmos.	Envie para um número de destinatário diferente.
`131026`	A mensagem não pôde ser entregue. As possíveis causas incluem um número que não está no WhatsApp, termos do WhatsApp não aceitos ou um aplicativo desatualizado.	Por meio de outro canal acordado, peça ao destinatário que confirme se pode enviar mensagens para a sua empresa, aceite os termos atuais do WhatsApp e atualize o WhatsApp. O código por si só não identifica uma causa definitiva.
`131047`	A janela de atendimento ao cliente de 24 horas expirou.	Envie um modelo aprovado apropriado ou aguarde uma nova mensagem do cliente antes de enviar uma resposta em formato livre.
`131049`	O WhatsApp reteve a mensagem para proteger o engajamento do destinatário.	Evite novas tentativas imediatas. Se você suspeitar de um limite de marketing do destinatário, aguarde pelo menos 24 horas antes de considerar outro envio. Primeiro verifique o consentimento e a relevância; aguardar não garante a entrega.
`131050`	O destinatário interrompeu as mensagens de marketing da sua empresa no WhatsApp.	Interrompa os envios de marketing para este destinatário. Não tente reenviar a mensagem de marketing com falha.

Erros de mensagem de Flow e modelo

Verifique o nome exato do modelo, o idioma, o status e as definições dos componentes na YCloud antes de tentar novamente.

Código	Significado	O que fazer
`132000`	O número de parâmetros de modelo fornecidos não corresponde ao modelo.	Forneça o número obrigatório de valores para cada componente.
`132001`	O modelo não existe no idioma solicitado ou não foi aprovado.	Verifique o nome, o código de idioma, a WABA e o status de aprovação.
`132005`	O texto do modelo excede o tamanho permitido.	Revise o modelo e os valores de texto fornecidos em relação aos limites de tamanho aplicáveis.
`132007`	O conteúdo do modelo viola uma política do WhatsApp.	Revise a violação relatada e corrija o conteúdo antes de reenviar.
`132012`	Os formatos dos parâmetros do modelo não correspondem à definição.	Verifique cada componente e tipo de parâmetro, incluindo botões e cabeçalhos de mídia.
`132015`	O modelo está pausado devido à baixa qualidade.	Interrompa os envios usando ele. Melhore seu conteúdo e retome apenas quando o modelo estiver aprovado e disponível para uso.
`132016`	O modelo está desativado permanentemente após repetidas pausas por qualidade.	Crie um substituto com conteúdo diferente e resolva o problema de qualidade antes de enviar.
`132068`	O Flow usado na mensagem está bloqueado.	Verifique o status do Flow e resolva o problema relatado antes de usá-lo novamente.
`132069`	O Flow está limitado e atingiu seu limite de envio restrito.	Revise a integridade do Flow e os envios recentes. Resolva o problema e aguarde antes de tentar novamente.

Consulte Gerenciar modelos do WhatsApp e Gerenciar Flows do WhatsApp.

Parâmetros de mensagem e mídia

Código	Significado	O que fazer
`100`	A solicitação contém um parâmetro incompatível ou inválido.	Leia os detalhes retornados e corrija o campo correspondente usando a referência de endpoint da YCloud.
`131008`	Um parâmetro obrigatório está ausente.	Adicione o campo ou componente identificado no erro.
`131009`	O valor de um parâmetro é inválido.	Corrija o valor, formato ou tamanho identificado nos detalhes do erro.
`131051`	O tipo de mensagem não é compatível.	Para envios de saída, use um tipo de mensagem compatível da YCloud. Para mensagens recebidas, trate o evento incompatível sem presumir que o conteúdo comum da mensagem esteja disponível.
`131052`	O WhatsApp não pôde baixar a mídia enviada pelo usuário.	Inspecione os detalhes do erro de entrada. Peça ao usuário para compartilhar o arquivo por outro canal acordado, se necessário.
`131053`	Não foi possível carregar a mídia usada na mensagem de saída.	Verifique o formato real do arquivo, tipo MIME, tamanho e acessibilidade. Corrija o arquivo ou a URL antes de tentar novamente.
`135000`	O WhatsApp relatou um erro não especificado de parâmetro de requisição.	Verifique a requisição em relação ao esquema da API da YCloud e preserve os detalhes retornados.

Consulte Enviar uma mensagem do WhatsApp e Carregar mídia do WhatsApp.

Conta, número de telefone e faturamento

Código	Significado	O que fazer
`368`, `131031`	A WABA está restrita ou bloqueada. Para `131031`, dados de verificação da conta também podem estar envolvidos.	Verifique o status da conta e os detalhes exatos do erro.
`130497`	A WABA não pode enviar mensagens para usuários em determinados países.	Verifique o destino e as restrições para a categoria da sua empresa. Não tente novamente para um destino não suportado sem alterações.
`131042`	O WhatsApp relatou um problema de pagamento ou faturamento da conta.	Verifique a conexão de faturamento da WABA. Isso é diferente do `BALANCE_INSUFFICIENT` da YCloud; apenas recarregar o saldo pode não resolver o problema.
`131045`, `133010`	O número de telefone comercial tem um problema de registro ou não está registrado.	Verifique a conexão e o status de registro do número na YCloud.
`131057`	A conta está temporariamente em modo de manutenção.	Aguarde o término da manutenção e tente novamente com recuo exponencial.

Erros de mensagens de marketing

Esses erros podem ocorrer quando a YCloud envia uma mensagem por meio da Marketing Messages API da Meta. Use os detalhes retornados para distinguir problemas de modelo, sincronização e roteamento.

Código	Significado	O que fazer
`131055`, `134100`	A rota upstream de marketing aceita apenas modelos de marketing.	Confirme se a mensagem pretendida usa um modelo de `MARKETING`. Modelos de utilidade e autenticação exigem uma rota de envio diferente.
`131063`	Os modelos de marketing estão desativados na rota Cloud API da conta.	Verifique a rota de envio de marketing e a configuração da conta.
`134101`	O modelo de marketing ainda está sendo sincronizado.	Aguarde 10 minutos antes de tentar novamente com o modelo recém-criado.
`134102`	O modelo não está disponível porque a sincronização ou a qualificação da conta está incompleta.	Verifique a qualificação da conta e se a sincronização do modelo foi concluída.
`132018`	A validação de parâmetros do modelo falhou.	Corrija os parâmetros identificados no erro e reenvie apenas após o sucesso da validação.

Para esta rota, 100 pode significar que a mensagem deve ser um modelo, e 131009 pode indicar parâmetros inválidos ou sincronização incompleta do modelo. Use os detalhes retornados para distinguir essas causas. Em caso de sincronização incompleta, aguarde 10 minutos antes de tentar novamente.

Erros temporários de serviço

Código	Significado	O que fazer
`1`	Uma requisição inválida ou um erro de servidor upstream.	Verifique a requisição primeiro. Se for válida, investigue um problema temporário de serviço.
`2`, `131016`	Um serviço upstream está temporariamente indisponível ou sobrecarregado.	Verifique o status da WhatsApp Business Platform e tente novamente para falhas temporárias com recuo delimitado.
`131000`	Uma falha não especificada do WhatsApp.	Verifique o status do serviço e os detalhes retornados. Use novas tentativas delimitadas apenas quando apropriado.

Tentar novamente e encaminhar

Corrija parâmetros inválidos, status do modelo, restrições da conta e problemas de mídia antes de tentar novamente.
Respeite cancelamentos de recebimento (opt-outs) e bloqueios de destinatários. Não tente novamente de forma automática para essas falhas.
Use recuo exponencial, variação aleatória (jitter) e um número máximo de tentativas para falhas temporárias. Aplique qualquer período de espera especificado acima ou na resposta.
Antes de reenviar após um tempo limite ou uma resposta ambígua, faça a reconciliação do status da mensagem para evitar duplicatas. externalId é um campo de correlação; não presuma que ele elimine o envio duplicado.

Se o erro persistir após as verificações acima, ou se precisar de ajuda com faturamento da conta, elegibilidade ou configuração da rota de envio, entre em contato com o suporte da YCloud. Inclua o horário da falha e o fuso horário, o endpoint, o código de erro exato e detalhes, o requestId da YCloud, o id da mensagem e wamid ou fbtrace_id quando disponíveis. Remova chaves de API e dados pessoais desnecessários.

Primeiros passos

Guias

Endpoints

Webhooks

Código de erro do WhatsApp

Encontrar o código de erro

Ler o código e os detalhes

Limites de envio e restrições de qualidade

Erros de destinatário e de entrega

Erros de mensagem de Flow e modelo

Parâmetros de mensagem e mídia

Conta, número de telefone e faturamento

Erros de mensagens de marketing

Erros temporários de serviço

Tentar novamente e encaminhar

​Encontrar o código de erro

​Ler o código e os detalhes

​Limites de envio e restrições de qualidade

​Erros de destinatário e de entrega

​Erros de mensagem de Flow e modelo

​Parâmetros de mensagem e mídia

​Conta, número de telefone e faturamento

​Erros de mensagens de marketing

​Erros temporários de serviço

​Tentar novamente e encaminhar

Encontrar o código de erro

Ler o código e os detalhes

Limites de envio e restrições de qualidade

Erros de destinatário e de entrega

Erros de mensagem de Flow e modelo

Parâmetros de mensagem e mídia

Conta, número de telefone e faturamento

Erros de mensagens de marketing

Erros temporários de serviço

Tentar novamente e encaminhar