Tratamento de erros

Toda falha retorna um envelope único, com um code estável — programe contra o código, nunca contra o texto de message (que pode mudar):

{
  "error": {
    "code": "outside_24h_window",
    "message": "Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead.",
    "request_id": "req_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "upstream_code": 131047
  }
}

Campo	Presença	Descrição
`code`	Sempre	Código estável do catálogo abaixo.
`message`	Sempre	Explicação em inglês, sempre acionável. Pode mudar sem aviso.
`request_id`	Sempre	Identificador da requisição. Informe ao suporte ao reportar um problema. O mesmo valor vem no header `X-Request-Id` de toda resposta (inclusive as de sucesso) — logue-o do seu lado.
`upstream_code`	Em erros do WhatsApp	Código numérico original da Meta, para diagnóstico fino.
`details`	Em `invalid_request` e nos erros de template	Lista de `{ path, message }`. Em `invalid_request`, aponta cada campo inválido do corpo. Nos erros de template, `path: "meta"` traz a explicação da Meta (quando ela envia uma) e `path: "campaigns"` lista as campanhas que impedem a exclusão.

Catálogo de códigos

Requisição e autenticação

Código	HTTP	Quando acontece	O que fazer
`invalid_request`	400	Corpo ou parâmetros inválidos.	Corrija os campos apontados em `details`.
`invalid_api_key`	401	Chave ausente, desconhecida ou revogada.	Confira o header `Authorization: Bearer sk_...`.
`lead_not_found`	404	O destinatário não é um lead da sua empresa.	Confira a empresa da chave; crie o lead com `POST /v1/leads` se necessário.
`message_not_found`	404	Nenhuma mensagem com esse id na sua empresa.	Use o `id` (`msg_...`) retornado no envio, não o `wamid`.
`stage_not_found`	404	O `stage_id` não existe na sua empresa.	Liste as etapas válidas com `GET /v1/funnel/stages` e use o `id` retornado.
`idempotency_conflict`	409	`Idempotency-Key` reutilizada com corpo diferente, ou requisição original ainda em andamento.	Use uma chave nova por operação; se em andamento, aguarde o `Retry-After`.
`lead_already_exists`	409	Já existe lead com esse telefone na empresa.	Recupere com `GET /v1/leads?phone=...` e siga o fluxo normalmente.

Configuração da conta

Código	HTTP	Quando acontece	O que fazer
`funnel_not_configured`	422	A empresa não tem etapas de funil configuradas.	Configure o funil no painel antes de criar leads por API.
`no_active_connection`	422	A empresa não tem conexão WhatsApp ativa.	Conecte um número no painel.
`connection_expired`	422	A autorização da conexão WhatsApp expirou.	Reconecte o número no painel.
`channel_capability_unsupported`	422	O tipo de conexão da empresa não suporta a operação (por exemplo, templates fora da Cloud API).	Verifique o tipo de conexão da empresa.

Envio (WhatsApp)

Código	HTTP	Quando acontece	O que fazer
`outside_24h_window`	422	Mensagem de formato livre fora da janela de 24 horas.	Envie um template aprovado.
`template_not_found`	422	Nome ou idioma do template não bate com nenhum aprovado.	Confira com `GET /v1/whatsapp/templates`.
`template_params_invalid`	422	Variáveis não batem com o template aprovado.	Confira quantidade, formato e idioma dos parâmetros.
`recipient_unavailable`	422	O destinatário não pode receber a mensagem (número sem WhatsApp, por exemplo).	Valide o número com o lead.
`media_unsupported`	422	O WhatsApp não conseguiu baixar ou processar a mídia do link.	Confira se o link é público e direto, o formato é suportado e o tamanho está no limite do tipo. Veja Enviando mídia.
`message_blocked`	422	A Meta bloqueou a mensagem (limites de qualidade/spam).	Reduza o volume para esse destinatário e revise a qualidade do conteúdo.
`rate_limit_exceeded`	429	Limite de requisições da sua chave excedido.	Aguarde o `Retry-After` e repita. Veja Rate limits.
`daily_quota_exceeded`	429	A cota diária da sua empresa acabou.	Aguarde o `Retry-After` (meia-noite de Brasília). Veja Rate limits.
`channel_rate_limit`	429	O WhatsApp está limitando o seu número.	Reduza o ritmo de envios e tente mais tarde.

Templates

Erros das rotas /v1/whatsapp/templates. Veja o guia de Templates.

Código	HTTP	Quando acontece	O que fazer
`template_not_found`	404	Nenhum template com esse id na sua conta. No envio de mensagem, o mesmo código vem com HTTP 422.	Confira o `id` (`tpl_...`) em `GET /v1/whatsapp/templates`.
`template_already_exists`	409	Já existe template com esse nome e idioma, ou ele ainda está em exclusão.	Use outro nome, ou edite o template existente.
`template_in_use`	409	Exclusão bloqueada: há campanha agendada, em andamento ou pausada usando o template.	Cancele a campanha ou troque o template dela. Até 10 campanhas vêm em `details`.
`template_status_conflict`	409	O status atual do template não permite a operação (editar em análise, excluir desabilitado).	Aguarde a mudança de status; acompanhe pelo webhook `whatsapp.template.updated`.
`template_invalid`	422	A Meta recusou a definição do template.	Corrija conforme a explicação em `details` (`path: "meta"`), quando a Meta enviar uma.
`template_limit_reached`	422	A conta atingiu o teto de templates (250, ou 6.000 com o negócio verificado).	Exclua templates sem uso ou verifique o negócio na Meta.

Nessas rotas, media_unsupported indica que o arquivo de exemplo do cabeçalho não pôde ser baixado ou não é aceito, e channel_rate_limit indica o limite da Meta de 100 criações de template por hora. Na criação, consulta por id, edição e exclusão, connection_expired (422) também aparece quando a conta conectada não tem permissão de gerenciar templates: reconecte o número no painel. Nessas mesmas rotas, channel_rate_limit (429), connection_expired e no_active_connection (422) chegam como vieram da conexão, e qualquer outra falha da Meta vira channel_error (502). A listagem (GET /v1/whatsapp/templates) mantém o comportamento de sempre e devolve a falha da Meta já traduzida para o catálogo acima.

Transitórios

Código	HTTP	Quando acontece	O que fazer
`channel_error`	502	Erro inesperado do provedor de mensagens.	Repita mais tarde, com `Idempotency-Key`.
`internal_error`	500	Erro interno da Superlead.	Repita mais tarde; se persistir, informe o `request_id` ao suporte.

Falhas assíncronas

Nem toda falha chega como erro HTTP: a Meta pode aceitar um envio (201) e falhá-lo segundos depois. Nesses casos, GET /v1/whatsapp/messages/{id} retorna status: failed com o campo error usando os mesmos códigos deste catálogo:

{
  "status": "failed",
  "error": { "code": "outside_24h_window", "upstream_code": 131047 }
}

Trate o error.code da consulta de status exatamente como trataria o code de uma resposta de erro síncrona. Para ser notificado da falha em vez de consultar, assine o evento whatsapp.message.updated — veja Webhooks.

Comece aqui

Conceitos

Tratamento de erros

Catálogo de códigos

Requisição e autenticação

Configuração da conta

Envio (WhatsApp)

Templates

Transitórios

Falhas assíncronas

​Catálogo de códigos

​Requisição e autenticação

​Configuração da conta

​Envio (WhatsApp)

​Templates

​Transitórios

​Falhas assíncronas

Catálogo de códigos

Requisição e autenticação

Configuração da conta

Envio (WhatsApp)

Templates

Transitórios

Falhas assíncronas