Erros e confiabilidade

Status HTTP

Status	Significado típico	Ação recomendada
`400`	payload ou parâmetro inválido	corrija o request; não repita igual
`401`	credencial ausente ou inválida	interrompa e revise/rotacione o token
`403`	operação não permitida	revise escopo, papel ou permissão no WhatsApp
`404`	recurso ou instância não encontrado	confirme identificadores e ownership
`409`	conflito ou operação já em andamento	consulte o estado antes de repetir
`429`	limite temporário	respeite `Retry-After` quando presente
`5xx`	falha temporária ou do provedor	registre contexto e tente novamente com limite

Sempre leia o schema e o corpo documentado da operação: alguns erros incluem error_key, mensagem do provedor ou endpoint de diagnóstico.

Política de retry

Pode repetir automaticamente leituras (GET) após falhas temporárias.
Em 429 e 503, respeite Retry-After quando retornado.
Use atraso exponencial com jitter e limite de tentativas.
Não repita cegamente um envio de mensagem após timeout: o primeiro request pode ter sido processado.
Antes de repetir uma mutação, consulte o estado ou reconcilie pelo ID retornado, webhook ou campo de rastreamento.

Exemplo de sequência de espera: 1s, 2s, 4s, 8s, sempre com pequena variação aleatória.

Webhooks

Seu receptor deve:

autenticar e validar o destino configurado;
rejeitar payloads maiores que o limite esperado;
responder rapidamente;
colocar processamento demorado em fila;
tolerar eventos repetidos e fora de ordem;
deduplicar por identificadores de evento/mensagem quando disponíveis.

Consulte /webhook/errors com o token da instância para diagnosticar falhas recentes. Para o webhook global, use /globalwebhook/errors com admintoken.

Observabilidade mínima

Registre operação, status HTTP, duração, instância interna/tenant e um correlation ID. Nunca registre tokens, conteúdo sensível de mensagens ou a query completa do SSE.