> ## 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. # Código de erro do WhatsApp > Consulte os códigos de erro de mensagens do WhatsApp e resolva falhas em mensagens enviadas pelo YCloud. 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](/pt/api-reference/guides/api-fundamentals/handle-errors). Consulte [Enviar uma mensagem do WhatsApp](/pt/api-reference/guides/whatsapp-platform/send-whatsapp-message) para obter os endpoints de envio e [Configurar webhooks](/pt/api-reference/guides/api-fundamentals/configure-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](/pt/documentation/whatsapp-business-platform/pricing-limits-and-quality/quality-and-delivery-controls) 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](/pt/api-reference/guides/whatsapp-platform/manage-whatsapp-templates) e [Gerenciar Flows do WhatsApp](/pt/api-reference/guides/whatsapp-platform/manage-whatsapp-flows). ## 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](/pt/api-reference/guides/whatsapp-platform/send-whatsapp-message) e [Carregar mídia do WhatsApp](/pt/api-reference/guides/whatsapp-platform/upload-whatsapp-media). ## 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](https://metastatus.com/whatsapp-business-api) 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](https://www.ycloud.com/console/#/app/getStarted). 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.