Erros e limites
Formato dos erros, códigos, o que tentar de novo e os limites da API.
Formato dos erros
Todo erro tem o mesmo formato:
{
"error": {
"code": "validation_error",
"message": "dados inválidos",
"details": { "chatId": "informe o chatId" }
}
}codeé estável: trate os erros por ele.messageé em português, para leitura humana, e pode mudar.details, quando existe, diz qual campo está errado.
Códigos
| Status | Código | Significado |
|---|---|---|
| 400 | bad_request | Corpo ou parâmetro inválido |
| 400 | url_not_allowed | URL recusada (endereço interno ou porta fora de 80/443) |
| 401 | missing_token, invalid_token | Token da instância ausente ou errado |
| 401 | invalid_client_token | Client-Token ausente ou errado (conta com Client-Token exigido) |
| 402 | payment_required | Instância sem assinatura ativa |
| 404 | not_found | Recurso não existe (mensagem, grupo, contato…) |
| 409 | instance_not_provisioned | A instância ainda não foi ativada |
| 413 | payload_too_large | Corpo acima do limite (para arquivos grandes, envie por URL) |
| 422 | validation_error | Campo inválido (details diz qual) |
| 422 | instance_not_connected | O número não está conectado ao WhatsApp (confira connectionStatus) |
| 422 | whatsapp_rejected | O WhatsApp recusou (ex.: sem permissão no grupo, número inexistente) |
| 429 | rate_limited | Muitas requisições; espere o tempo do header Retry-After |
| 429 | trial_limit_reached | Limite diário de mensagens do teste grátis |
| 429 | queue_full | A fila da instância chegou a 10.000 mensagens pendentes |
| 429 | too_many_attempts | Muitos pedidos de código de pareamento; aguarde alguns minutos |
| 501 | not_supported_by_provider | A rota não existe na API oficial (instância Meta) |
| 501 | official_api_only | A rota só existe na API oficial (instância API OnZap) |
| 501 | not_supported | Recurso indisponível na API OnZap |
| 4xx/502 | whatsapp_error | Erro do WhatsApp ao processar (a message explica) |
| 503 | whatsapp_unavailable | Serviço temporariamente fora; tente de novo (veja Retry-After) |
| 504 | whatsapp_timeout | O WhatsApp demorou demais para responder |
Quando tentar de novo
- 429, 502 e 503: tente de novo depois do tempo do header
Retry-After, ou com espera crescente (1 s, 2 s, 4 s…). - Outros 4xx: não adianta repetir; corrija a requisição.
- Timeout num envio: antes de reenviar, confira nos eventos (
message.anycomfromMe: true) se a mensagem já saiu, para não mandar em duplicidade.
Limites
| Limite | Valor |
|---|---|
| Requisições por instância | 20 por segundo, com rajadas curtas de até 40 |
| Corpo JSON | até 1 MB; com arquivo em base64, até 70 MB |
| Fila de envio | até 10.000 mensagens pendentes por instância |
| Teste grátis | até 300 mensagens por dia |
| Webhooks | até 5 endereços por instância |
| Links de mídia | válidos por 24 horas |