Limites de requisição
Quantas requisições a API aceita, como reconhecer o limite e quanto esperar.
Limite geral
A API aceita até 500 requisições por minuto por usuário. As chamadas com token de login contam para o usuário do token; as chamadas sem token contam para o endereço IP de origem.
A contagem é feita em janelas fixas de 60 segundos: a janela começa na primeira requisição e o contador zera 60 segundos depois.
Quando o limite é atingido
A API responde 429 Too Many Requests, com o tempo que falta para a janela zerar em expected.retry_after:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"error": true,
"message": "Rate limit exceeded",
"expected": {
"retry_after": "17s"
}
}retry_after é uma duração em texto, como 17s ou 1m0s. Essa resposta não traz o cabeçalho Retry-After nem um code. Espere o tempo indicado antes de repetir.
Se o controle de limite estiver indisponível, a API também responde 429, com a mensagem Service temporarily unavailable, please retry. Espere alguns segundos e repita.
As respostas de sucesso não trazem cabeçalhos com a cota restante. Controle o ritmo do seu lado e trate o 429 quando ele vier.
Limites de rotas específicas
Algumas rotas têm um limite próprio, contado à parte:
| Rota | Limite | Contado por |
|---|---|---|
POST /auth/login | 100 por minuto | Endereço IP |
POST /auth/forgot-password | 3 por hora | Endereço IP |
POST /auth/reset-password | 3 por hora | Endereço IP |
POST /medias e POST /leads/imports | 10 por segundo | Endereço IP |
POST /whatsapp/business-phones/{id}/request-verification e POST /whatsapp/business-phones/{id}/verify-code | 5 por dia | Endereço IP |
GET /cep/search | 20 por minuto | Endereço IP |
POST /webhooks/workflow/{token} (gatilho de fluxo) | 120 por minuto | Endereço IP |
Além do limite por endereço, o login recusa novas tentativas depois de várias senhas erradas seguidas: a resposta é 429 com o código AUTH_RATE_LIMIT_EXCEEDED e o cabeçalho Retry-After, em segundos.
API de e-mail transacional
As rotas que usam a chave de API (/email/transactional/messages) não entram no limite geral. Elas têm limites próprios:
| Limite | Valor |
|---|---|
| Por chave de API | 600 requisições por minuto |
| Por endereço IP de origem | 1.200 requisições por minuto |
O limite por IP é verificado antes da chave, então requisições com chave inválida também contam para ele. Ao atingir qualquer um dos dois, a resposta é 429 com o código api_key_rate_limited, o cabeçalho Retry-After e os mesmos segundos em details.retry_after_seconds:
{
"error": true,
"code": "api_key_rate_limited",
"message": "Limite de requisições atingido; aguarde e tente de novo.",
"details": {
"retry_after_seconds": 17
}
}Os limites do próprio envio de e-mail, como o limite diário do domínio, estão em API de e-mail transacional.
Boas práticas
- Espalhe as chamadas no tempo em vez de disparar muitas de uma vez.
- Ao receber
429, espere o tempo indicado e repita; repetir antes só gera novas recusas. - Guarde em cache os dados que mudam pouco, como a lista de workspaces e de departamentos.
- Para acompanhar mudanças em tempo real, prefira as conexões WebSocket a consultar a mesma lista repetidamente.
Updated 17 days ago