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`	Lista de `{ path, message }` apontando cada campo inválido do corpo.

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.
`channel_rate_limit`	429	O WhatsApp está limitando o seu número.	Reduza o ritmo de envios e tente mais tarde.

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)

Transitórios

Falhas assíncronas

​Catálogo de códigos

​Requisição e autenticação

​Configuração da conta

​Envio (WhatsApp)

​Transitórios

​Falhas assíncronas

Catálogo de códigos

Requisição e autenticação

Configuração da conta

Envio (WhatsApp)

Transitórios

Falhas assíncronas