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.

Limite de chamadas

Todas as rotas chamadas com o token de uma instância dividem a mesma cota:

Quem	Limite padrão
Instância (`token`)	10 chamadas por segundo, com rajada de até 20
Administração (`admintoken`)	10 chamadas por segundo por servidor, com rajada de até 20
`POST /chat/details`	também até 4 consultas ao mesmo tempo por instância; a seguinte espera até 2 segundos por uma vaga

Acima do limite, a API responde 429 com {"error": "rate limit exceeded"} e o header Retry-After, com os segundos até a próxima chamada ser aceita. Espere esse tempo antes de repetir.

No navegador, o Retry-After não fica legível, porque não é exposto no CORS: espere cerca de 1 segundo e tente de novo.
Para enviar muitas mensagens, use Mensagem em massa ou async: true, em vez de muitas chamadas seguidas.
Para mostrar fotos numa lista de conversas, use POST /chat/avatar, mais leve que /chat/details.

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. O campo stage diz onde a entrega parou: http quando o seu receptor respondeu com erro ou não respondeu; config ou um *_queue_full (com attempts: 0) quando o evento nem chegou a ser enviado. Muitos *_queue_full indicam receptor lento: responda antes de processar.

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.