Usar a API

Erros e como resolver

Todo erro vem com um codigo estável para o seu código tratar e uma mensagem em português dizendo o que fazer.

Formato

json

{ "ok": false, "erro": { "codigo": "fora_da_janela_24h", "mensagem": "Esse contato não falou com a empresa nas últimas 24 h. Pelo WhatsApp, só dá para mandar um template." } }

Erros da API (na hora da chamada)

HTTP	Quando	Exemplos de `codigo`
400	Parâmetro faltando ou inválido	`parametro_obrigatorio`, `parametro_invalido`, `json_invalido`
401	Chave ausente, inválida ou revogada	`nao_autorizado`
403	Sem permissão, plano ou dono da chave fora da empresa	`sem_permissao`, `plano_sem_api`, `chave_sem_dono`
404	Não encontrado	`contato_nao_encontrado`, `ferramenta_inexistente`
409	A regra não permite agora	`fora_da_janela_24h`, `contato_sem_telefone`, `sem_numero`
429	Limite atingido (a mensagem diz quando volta)	`limite_por_minuto`, `limite_por_dia`, `limite_de_envios_por_dia`, `limite_de_envios_por_mes`
500	Erro nosso: tente de novo (com a mesma `chave_idempotencia`)	`erro_interno`

Erros do WhatsApp (depois do envio)

Quando a Meta recusa a entrega, o aviso mensagem.falhou chega com erro.codigo, erro.motivo e erro.como_resolver. Os mais comuns:

Código	Motivo	O que fazer
`131047`	Janela de 24h fechada	O cliente não escreveu nas últimas 24h: use um template aprovado.
`131026`	Mensagem não entregável	O número não tem WhatsApp ou não aceitou os termos novos. Não insista com esse contato.
`131049`	Limitado pela Meta por baixo engajamento	Política da Meta para marketing com pouca interação. Mande menos para listas frias.
`131048`	Limite de envio do número	Número novo começa com teto diário baixo, que sobe com envios consistentes. Envie em lotes menores.
`131056`	Muitas mensagens para o mesmo contato	Espace os envios para essa pessoa.
`132001`	Template não encontrado	Confira se está aprovado e no idioma certo (`listar_templates`).
`132012`	Variáveis do template erradas	A quantidade ou o formato das `variaveis` não bate com o template.
`131042`	Forma de pagamento não configurada na Meta	A conta do WhatsApp Business precisa de moeda e cartão na Meta. Sem isso, nenhuma entrega sai.
`130472`	Número em experimento da Meta	Ocorrência aleatória da Meta. Tente mais tarde.

Falha temporária da Meta (instabilidade, 131000, 131016) não vira mensagem.falhou na primeira tentativa: a mensagem fica na fila e é reenviada sozinha.