Códigos de erro da API do WhatsApp

Qual é o formato de um erro da API?

HTTP/1.1 409 Conflict
content-type: application/json

{ "erro": "janela de 24h expirada — use um template aprovado", "codigo": "JANELA_EXPIRADA" }

• erro é uma mensagem em português para pessoas; pode mudar de texto. codigo é estável: trate pelo código.
• Erros de validação de campo (400) muitas vezes vêm só com erro, dizendo qual campo está errado.
• Quando a Meta recusa, a resposta é 502 com o nosso codigo e o codigo_meta original.
• A API nunca devolve detalhes internos (stack trace). Em 500, a resposta é só { "erro": "falha interna" }.

Erros de autenticação e permissão (401, 403)

Erros de assinatura e cartão (402)

Com a assinatura pausada, cancelada ou aguardando cartão, os webhooks de saída também ficam retidos na fila (sem perder eventos) até a regularização.

Erros de validação e recurso não encontrado (400, 404)

Erros de regra de negócio (409)

Quais erros da Meta a API traduz (502)?

Quando a Cloud API da Meta recusa um envio, a resposta é 502 com um código nosso e o original em codigo_meta:

{ "erro": "Este número não está no WhatsApp ou bloqueou o remetente.", "codigo": "NUMERO_NAO_WHATSAPP", "codigo_meta": 131026 }

Os códigos 133005 e 133010 (número já registrado) são tratados na conexão do número e não chegam às rotas da API. Falhas que a Meta informa depois do envio (mensagem aceita e não entregue) chegam pelo evento message.status com status: "failed" e o código da Meta em erro.codigo.

Erros do download de mídia (410, 503)

O POST /media-download separa falha definitiva de passageira:

Erros do servidor MCP

No MCP, erro de negócio volta como resultado da ferramenta com isError: true e o mesmo { erro, codigo } das rotas REST, para a IA explicar ao usuário. Além dos códigos acima, as ferramentas de configuração usam:

Erros de protocolo vêm como erro JSON-RPC: -32700 (JSON inválido), -32600 (pedido inválido ou lote), -32601 (método não suportado), -32602 (ferramenta, recurso ou prompt inexistente, ou ferramenta não liberada no plano) e -32603 (falha interna). Sem credencial, o MCP responde 401 com o header WWW-Authenticate que inicia o login OAuth.

Erros na entrega de webhooks

Não são respostas da API, mas aparecem no painel (Integrações, lista de entregas) e em listar_webhooks no MCP:

• HTTP 4xx/5xx: o seu servidor respondeu erro. Conta como falha e entra no retry.
• HTTP 3xx: redirecionamento não é seguido: cadastre a URL final.
• destino não permitido: URL sem https, ou que aponta para endereço interno ou privado.
• TimeoutError: o seu servidor não respondeu em 10 segundos. Responda 200 antes de processar.

Detalhes de retry e assinatura em webhooks.

E os erros 500?

500 { "erro": "falha interna" } é falha do nosso lado. Pode tentar de novo com espera. Exceção: no envio, se a Meta já aceitou a mensagem e a gravação falhou, repetir mandaria a mensagem duas vezes; antes de reenviar, confira o histórico com GET /messages-list. Se persistir, fale com o suporte informando a rota e o horário.

Perguntas frequentes