Erros

Como tratar#

• 4xx (menos 429): o pedido está errado. Corrija antes de repetir; a mesma chamada vai falhar igual.
• 429: espere os segundos de Retry-After e repita (veja Limites de uso).
• 5xx: repita com espera crescente. No envio de mensagem, com a mesma Idempotency-Key.

{
  "erro": {
    "codigo": "janela_fechada",
    "mensagem": "A janela de 24 horas desta conversa está fechada. Na API oficial do WhatsApp, só um modelo aprovado reabre a conversa.",
    "requisicao_id": "5d2f0c3e-8b1a-4c6e-9f7d-1a2b3c4d5e6f"
  }
}

Conta restrita pela Meta (conta_restrita)#

Enquanto a Meta restringe o número por spam e a trava de spam da organização está ligada (Configurações > API), o envio barrado volta 422 conta_restrita na hora, sem enviar nada. O erro traz os campos do objeto RestricaoMeta (os mesmos de caixas[].conexoes[].restricao_meta no GET /me): ate e desde (ISO-8601 UTC), ate_fonte (meta ou padrao), escopo (iniciadas = só modelos; tudo = nada sai), motivo (meta_131031, meta_368, meta_131048, account_restriction, account_disabled, outro), motivo_texto, caixa_id e retry_after_s. O cabeçalho Retry-After repete retry_after_s: mostre ate ao usuário e tente de novo depois desse tempo. Com a trava desligada, nada é barrado e a restrição só aparece no GET /me.

{
  "erro": {
    "codigo": "conta_restrita",
    "mensagem": "A Meta restringiu esta conta por spam até 25/10/2026 às 11:00 (horário de Brasília): mensagens que abrem conversa (modelos) estão barradas; respostas dentro da janela de 24 h saem.",
    "ate": "2026-10-25T14:00:00Z",
    "desde": "2026-10-24T14:00:00Z",
    "ate_fonte": "padrao",
    "escopo": "iniciadas",
    "motivo": "meta_131031",
    "motivo_texto": "A Meta travou a conta do WhatsApp (131031).",
    "caixa_id": "0b6f5a52-3c1d-4e8f-9a7b-2c4d6e8f0a1b",
    "retry_after_s": 86400,
    "api_recusa": true,
    "requisicao_id": "5d2f0c3e-8b1a-4c6e-9f7d-1a2b3c4d5e6f"
  }
}

Status HTTP#

Perguntas frequentes#

O que mando ao suporte?#

O requisicao_id da resposta (também no cabeçalho X-Request-Id), a hora e a rota chamada. Nunca mande a chave.

Por que recebo 404 num id que existe?#

Porque ele é de outra organização ou foi apagado. A chave enxerga só a organização dela e, para a API, as duas coisas são iguais.

A mensagem do erro pode mudar?#

Pode. A mensagem é para pessoas e pode mudar de texto. O codigo não muda: é ele que o seu código deve testar.

Todos os códigos#