Use este catálogo quando você já tem um código, mensagem de erro ou sintoma e precisa encontrar rapidamente a causa provável e a primeira ação recomendada.

Se você ainda não sabe por onde começar, leia primeiro [Mensagens não enviam: como diagnosticar](/hc/ajuda/articles/mensagens-nao-enviam-como-diagnosticar). Se o erro for de template, mídia, e-mail, Meta ou automação, os artigos específicos continuam sendo a melhor leitura guiada.

## Como pesquisar neste artigo

- Pesquise pelo código exato, como `132001`, `131047`, `63016`, `550`, `META-190`, `EMAIL-AUTH` ou `API-400/422`.
- Pesquise pela mensagem exibida, como `Template does not exist`, `Rate limit exceeded`, `OAuthException`, `relay denied` ou `content can't be blank`.
- Pesquise pelo sintoma, como `pendente`, `enviada mas não entregue`, `mídia não envia`, `token inválido`, `fora da janela` ou `bounce`.

## Erros gerais da IAra e de canais

| Código/família | Mensagens comuns | Causa provável | O que fazer |
|---|---|---|---|
| `GEN-001` | Falha ao enviar, mensagem não enviada, não foi possível concluir o envio | A causa real ficou em uma camada inferior: credencial, política do canal, timeout, payload ou provedor. | Reduza para o menor teste possível: texto simples, sem automação e sem anexo. |
| `GEN-002` | Pendente, processing, em processamento | Fila, job, confirmação de webhook ou dependência temporariamente indisponível. | Aguarde, teste outro contato e veja se o problema afeta o canal inteiro. |
| `GEN-003` | Sent sem delivered/read, enviada mas não entregue | Aceite inicial seguido de rejeição posterior, callback ausente, bloqueio do destinatário ou status atrasado. | Use o status do canal/provedor como fonte principal de entrega real. |
| `GEN-004`, `403` | forbidden, access denied, permission denied, insufficient permission | Token, escopo, conexão, papel do usuário ou autorização insuficiente. | Reconecte o canal com a conta correta e aceite todas as permissões solicitadas. |
| `GEN-005`, `404` | not found, conversation not found, inbox not found | Recurso apagado, ID incorreto, conta errada, cache antigo ou referência inválida. | Confirme conta, caixa, contato, conversa e IDs usados no envio. |
| `GEN-006`, `422` | unprocessable entity, invalid payload, content can't be blank, unsupported content | Conteúdo vazio, campo obrigatório ausente, JSON fora do schema, anexo inválido ou tipo não suportado. | Corrija o payload ou teste texto simples sem anexo/variável. |
| `GEN-007`, `429` | rate limit exceeded, throughput exceeded, too many requests | Limite por app, canal, número, destinatário, página, provedor ou automação. | Reduza ritmo, use fila e aguarde antes de tentar de novo. |
| `GEN-008`, `500`, `502`, `503`, `504`, timeout | server error, webhook não responde, conexão encerrada | Instabilidade temporária, provedor fora, DNS/TLS, webhook lento ou latência alta. | Trate como temporário, aplique espera/backoff e monitore recorrência. |

## WhatsApp: códigos Meta e Cloud API

| Código | Nome curto | Leitura operacional | O que fazer |
|---|---|---|---|
| `1`, `WA-1/2/131000/135000` | API unknown | Erro genérico da API ou solicitação sem detalhe suficiente. | Teste de novo com texto simples e colete o retorno completo se persistir. |
| `2`, `WA-1/2/131000/135000` | API service | Sobrecarga ou indisponibilidade temporária da API. | Aguarde e tente novamente com intervalo. |
| `368`, `WA-368/130497/131031` | Temporarily blocked | Bloqueio temporário por política/compliance. | Interrompa envios e revise política, qualidade e status da conta. |
| `130429`, `WA-130429` | Throughput exceeded | Taxa global de envio excedida. | Reduza volume, segmente envios e use backoff. |
| `130472`, `WA-130472` | User number in experiment | Número do destinatário em experimento ou limitação do canal. | Use canal alternativo ou tente mais tarde. |
| `130497`, `WA-368/130497/131031` | Country restriction | Restrição por país ou alcance geográfico. | Verifique restrição da conta/canal antes de reenviar. |
| `131000`, `WA-1/2/131000/135000` | Something went wrong | Erro genérico sem detalhe suficiente. | Reproduza com payload mínimo e colete o retorno bruto. |
| `131005`, `WA-131005/131008` | Access denied | Acesso negado, token/escopo/permissão inadequados. | Reconecte ou revise permissões do canal. |
| `131008`, `WA-131005/131008` | Required parameter missing | Parâmetro obrigatório ausente. | Complete destinatário, template, componentes ou campos obrigatórios. |
| `131016`, `WA-131016/131057` | Service unavailable | Serviço temporariamente indisponível. | Aguarde normalização e tente novamente com intervalo. |
| `131021` | Sender equals recipient | Remetente e destinatário são o mesmo número. | Use outro número para teste/envio. |
| `131026`, `WA-131026` | Message undeliverable | Mensagem não entregável ao destinatário. | Confirme número, WhatsApp ativo, bloqueio, atualização do app e aceite de termos. |
| `131031`, `WA-368/130497/131031` | Account locked | Conta bloqueada. | Trate como incidente de conta/política e peça ajuda à Digi2B com evidências. |
| `131037` | Display name not approved | Nome de exibição ou número em condição que exige aprovação. | Revise aprovação do número/nome no provedor/canal. |
| `131042`, `WA-131042` | Business eligibility/payment issue | Elegibilidade comercial, pagamento, WABA ou conta com problema. | Regularize conta comercial, pagamento e status do número. |
| `131047`, `WA-131047` | Re-engagement message | Tentativa de texto livre fora da janela de 24h. | Use template aprovado para iniciar ou retomar conversa. |
| `131049`, `WA-131049` | Healthy ecosystem engagement | Entrega suprimida por proteção, frequência, qualidade ou elegibilidade. | Reduza frequência, melhore segmentação e revise qualidade dos templates. |
| `131051`, `WA-131051` | Unsupported message type | Tipo de mensagem não suportado. | Troque por texto, link ou formato aceito pelo canal. |
| `131052`, `WA-131052/131053` | Media download error | O canal não conseguiu baixar a mídia. | Use URL pública, estável, sem login, com content-type correto e sem expiração curta. |
| `131053`, `WA-131052/131053` | Media upload error | Upload, formato, tamanho, codec ou processamento da mídia rejeitado. | Reduza tamanho, troque formato e teste arquivo simples. |
| `131056`, `WA-131056` | Pair rate limit hit | Limite por par remetente-destinatário. | Aguarde antes de reenviar para o mesmo contato. |
| `131057`, `WA-131016/131057` | Account in maintenance mode | Conta/número em manutenção ou upgrade. | Aguarde e evite volume alto até normalizar. |
| `132000`, `WA-132000` | Template param count mismatch | Quantidade de variáveis diferente do template. | Envie exatamente os parâmetros exigidos, na ordem correta. |
| `132001`, `WA-132001` | Template does not exist | Template inexistente, não aprovado, idioma incorreto ou não sincronizado. | Confira nome técnico, idioma, categoria e status do template. |
| `132005` | Template hydrated text too long | Texto final do template excede limite. | Reduza variáveis longas e conteúdo dinâmico. |
| `132007` | Template format character policy violated | Violação de política de caracteres/formatação. | Revise quebras, símbolos, emojis e conteúdo sensível. |
| `132012`, `WA-132012` | Template parameter format mismatch | Tipo ou estrutura da variável incorreta. | Corrija texto, moeda, data, mídia, botão ou components. |
| `135000`, `WA-1/2/131000/135000` | Generic user error | Erro genérico de requisição/usuário. | Refine o diagnóstico com retorno bruto, contato, template e payload usado. |

## Facebook, Instagram e Messenger

| Código/família | Mensagens comuns | Causa provável | O que fazer |
|---|---|---|---|
| `META-190` | OAuthException, token inválido, token expirado, sessão invalidada | Token expirou, sessão foi revogada ou a conta perdeu acesso. | Reconecte o canal com o usuário correto. |
| `META-PERM` | permissões insuficientes, access denied, pages_messaging ausente, task de mensagem ausente | Escopos, tarefas da página ou permissões do app ausentes. | Reconecte aceitando todas as permissões e confirme papel administrativo. |
| `META-WINDOW` | não é possível enviar fora da janela/contexto, usuário não iniciou conversa | Política do canal limita contato não solicitado. | Aguarde nova interação ou use mecanismo oficial permitido pelo canal. |
| `META-LINK` | página desconectada, Instagram não vinculado, webhook incompleto, conta não profissional | Página, conta profissional, vínculo Página-Instagram ou subscribed fields incorretos. | Refaça vínculo e reconecte a caixa de entrada. |

## E-mail, SMTP, DNS e bounces

| Código/família | Mensagens comuns | Causa provável | O que fazer |
|---|---|---|---|
| `EMAIL-AUTH` | authentication failed, invalid credentials, username/password not accepted, SMTP AUTH disabled | Senha, app password, MFA, SMTP AUTH ou permissão da caixa. | Atualize credenciais e método de autenticação. |
| `EMAIL-TLS` | TLS handshake failed, certificate error, EOF, connection refused, timeout | Porta, SSL/TLS/STARTTLS, certificado, firewall, DNS ou indisponibilidade. | Corrija servidor, porta e política de segurança. |
| `EMAIL-DNS` | e-mail cai em spam, rejeição por política, domínio desalinhado | SPF, DKIM ou DMARC ausente/incorreto. | Ajuste DNS do domínio remetente. |
| `EMAIL-4XX`, `4.x.x` | `421`, `450`, `451`, `452` | Falha temporária do servidor remoto ou limitação transitória. | Aguarde e tente novamente com intervalo. |
| `EMAIL-5XX`, `5.x.x` | `550`, `551`, `552`, `553`, `554` | Falha permanente: endereço, política, remetente, conteúdo ou tamanho. | Corrija antes de reenviar. |
| `EMAIL-SIZE/POLICY` | message too big, relay denied, delivery not authorized | Anexo grande, remetente não autorizado, relay bloqueado ou política de conteúdo. | Reduza anexo, use link e verifique remetente/autorização. |

### Códigos SMTP e enhanced status

| Código | Leitura operacional | Natureza | O que fazer |
|---|---|---|---|
| `421` | Service not available, servidor indisponível. | Temporário | Tente depois. |
| `450` | Mailbox unavailable temporário. | Temporário | Aguarde e tente novamente. |
| `451` | Local error in processing. | Temporário | Aguarde; se persistir, peça o bounce completo. |
| `452` | Recursos/armazenamento insuficientes. | Temporário | Reduza volume/tamanho e tente depois. |
| `500` | Syntax error. | Permanente até correção | Corrija comando/payload SMTP. |
| `501` | Syntax error in parameters. | Permanente até correção | Corrija parâmetros do endereço/mensagem. |
| `502` | Command not implemented. | Permanente até correção | Revise compatibilidade do servidor. |
| `503` | Bad sequence of commands. | Permanente até correção | Revise sequência/autenticação SMTP. |
| `504` | Parameter not implemented. | Permanente até correção | Remova parâmetro não suportado. |
| `550` | Mailbox unavailable, no access ou rejeição por política. | Permanente | Corrija destinatário, remetente ou política. |
| `551` | User not local. | Permanente | Confirme endereço correto ou redirecionamento. |
| `552`, `5.3.4` | Exceeded storage, too much mail data, message too big. | Pode ser permanente | Reduza anexo ou use link. |
| `553` | Mailbox name invalid. | Permanente | Corrija endereço. |
| `554`, `5.7.1` | Transaction failed, delivery not authorized. | Permanente até correção | Revise autenticação, reputação, conteúdo e DNS. |

## Twilio e provedores intermediários

| Código/família | Nome curto | Leitura operacional | O que fazer |
|---|---|---|---|
| `63005`, `TW-63005/63021` | Channel did not accept content | Canal recusou o conteúdo. | Ajuste formato, componentes, mídia ou política do conteúdo. |
| `63010` | Internal error | Erro interno do provedor. | Aguarde e colete retorno completo se persistir. |
| `63012` | Provider internal service error | Serviço interno do provedor falhou. | Trate como temporário e monitore. |
| `63013`, `TW-63013` | Channel policy violation | Violação de política do canal. | Corrija conteúdo e reenvie apenas após validação. |
| `63016`, `TW-63016` | Outside allowed window | Fora da janela permitida. | Use template oficial ou aguarde nova interação. |
| `63017`, `TW-63017/63018` | Rate limit exceeded | Limite excedido no provedor. | Reduza ritmo e aplique espera. |
| `63018`, `TW-63017/63018` | Rate limit exceeded for channel | Limite excedido no canal. | Segmente envios e use fila. |
| `63021`, `TW-63005/63021` | Invalid content | Conteúdo inválido. | Corrija estrutura, variáveis, mídia ou texto. |
| `63040`, `TW-63040/63041/63042` | Template rejected | Template rejeitado. | Corrija e submeta novamente ou use outro template. |
| `63041`, `TW-63040/63041/63042` | Template paused | Template pausado. | Use outro template ativo e revise qualidade. |
| `63042`, `TW-63040/63041/63042` | Template disabled | Template desabilitado. | Substitua o template e revise política. |
| `TW-PROV-400/401/403/500/502` | Erro do provedor intermediário | API disabled, invalid api_key, endpoint blocked, internal server error, WhatsApp API not available. | Regularize credencial, pagamento, status da conta ou disponibilidade do provedor. |

## API, webchat, bots, webhooks e automações

| Código/família | Mensagens comuns | Causa provável | O que fazer |
|---|---|---|---|
| `API-400/422`, `400`, `422` | invalid payload, contact not found, identifier invalid, conversation not eligible, unprocessable entity | Schema quebrado, identificador errado, sessão encerrada, canal incompatível ou conteúdo inválido. | Corrija payload, contato, conversa e tipo de mensagem. |
| `API-CTX` | automação dispara mas mensagem não sai, sessão não elegível, regra fora de contexto | Estado da conversa/canal não permite aquela ação. | Ajuste condição, janela, status, handoff e elegibilidade. |
| `API-WH` | evento não chega, status não atualiza, bot não dispara, webhook silencioso | Webhook/evento externo indisponível, inválido, atrasado ou desconectado. | Revalide URL, autenticação, assinatura, resposta 2xx e processamento real do endpoint. |
| `403` em API | forbidden, permission denied | Token/escopo/conta sem permissão. | Revise credencial e permissões da integração. |
| `404` em API | not found, conversation not found, contact not found | ID incorreto, recurso apagado ou conta errada. | Corrija IDs e ambiente usado. |
| `429` em API/automação | too many requests, rate limit exceeded | Automação repetindo envios ou volume alto. | Deduplique gatilhos, use fila e aplique intervalo. |
| `5xx`/timeout em webhook | endpoint não responde, conexão encerrada, status não atualiza | Instabilidade externa, DNS/TLS, latência ou endpoint fora. | Aplique retry controlado e monitore health do endpoint. |

## Problemas sem código explícito

| Sintoma | Possível causa | O que fazer |
|---|---|---|
| Falha sem código na tela | Detalhe real ficou no provedor, webhook ou payload. | Teste mensagem simples e colete horário, canal, conversa e print. |
| Mensagem aceita, mas sem delivered/failed | Callback/status webhook ausente ou atrasado. | Aguarde, valide status no canal/provedor e evite reenviar em massa. |
| Canal degradado | Parte dos envios funciona, parte fica em sent/pendente. | Compare horários e veja se afeta todos os contatos ou só alguns. |
| Timeout de rede | A plataforma não sabe se o request foi aceito. | Aguarde reconciliação antes de reenviar. |
| Configuração incompleta | Conexão parece ativa, mas falta scope, task, webhook field ou vínculo. | Reconecte o canal e revise permissões. |
| Desconexão silenciosa | Token funciona para algumas chamadas, mas não para enviar. | Refaça a conexão com o usuário correto. |
| Manual funciona, automação falha | Regra, payload, variável ou contexto inválido. | Revise automação/API antes de culpar o canal. |
| Só mídia falha | URL, MIME, extensão, codec, tamanho ou expiração. | Teste arquivo menor em formato comum e URL pública. |
| E-mail sai, mas cai em spam | SPF, DKIM, DMARC, reputação ou cabeçalhos. | Corrija autenticação de domínio antes de aumentar volume. |

## O que separar antes de pedir ajuda à Digi2B

- Canal, caixa de entrada, conversa, horário exato, código exibido e tipo de mensagem.
- Template usado, idioma, variáveis, arquivo/URL de mídia, bounce de e-mail ou retorno bruto do provedor quando estiver disponível.