Rate limit e tratamento de erros

​

Regra geral

​

Envios não são idempotentes

1. Consulte GET /queue filtrando pelo phone. Se a mensagem estiver lá, ela chegou.
2. Se você tem o webhook delivery, espere alguns segundos: ele confirma o envio pelo message_id.
3. Só então reenvie.

​

Dimensionando o cliente

• O limite é por instância: 60 req/s sustentadas, com rajadas de 120. Poucas integrações chegam perto disso, e o gargalo real de envio é o intervalo anti-ban da fila.
• Use conexões HTTP keep-alive e um pool pequeno. Centenas de conexões simultâneas para a mesma instância só disputam o mesmo bucket.
• Consultas repetitivas (GET /status em loop, GET /qr-code a cada segundo) contam no limite. Prefira o webhook instance_status. Se precisar consultar, a cada 10 s basta.
• Um timeout de cliente de 30 s é razoável. Ações imediatas falam com o aparelho e podem levar alguns segundos, enquanto os envios respondem em milissegundos.

​

Lendo os headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 1
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Too many requests" } }

​

Erros de validação

{ "error": { "code": "invalid_request", "message": "phone: Invalid input", "details": { "issues": [{ "path": "phone", "message": "Invalid input" }] } } }

​

Registrando para depurar