# 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:

1. autenticar e validar o destino configurado;
2. rejeitar payloads maiores que o limite esperado;
3. responder rapidamente;
4. colocar processamento demorado em fila;
5. tolerar eventos repetidos e fora de ordem;
6. 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.