Guias
Limites de requisição
Quantas requisições a API aceita, como reconhecer o limite e quanto esperar.
Limite geral
Cada requisição conta num destes limites:
| Quem chama | Limite | Contado por |
|---|---|---|
| Token de login | 500 por minuto | Usuário do token |
Chave de integração (wsk_, só na API /v1) | 600 por minuto | Chave |
| Sem token válido | 1.200 por minuto | Endereço IP de origem |
Uma chave de integração conta também no limite do endereço IP antes de ser conferida.
A contagem é feita em janelas fixas de 60 segundos: a janela começa na primeira requisição e o contador zera 60 segundos depois.
Cota restante
Toda resposta de uma rota com limite traz a cota da janela atual:
| Cabeçalho | Valor |
|---|---|
X-RateLimit-Limit | Requisições aceitas na janela |
X-RateLimit-Remaining | Quantas ainda cabem na janela |
X-RateLimit-Reset | Segundos inteiros até a janela zerar |
Quando o limite é atingido
A API responde 429 Too Many Requests com o código rate_limited, o cabeçalho Retry-After e details.retryAfterSeconds, os dois em segundos inteiros:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17
{
"error": true,
"code": "rate_limited",
"message": "Limite de requisições atingido; tente de novo depois do tempo indicado",
"details": {
"retryAfterSeconds": 17
}
}Espere os segundos indicados antes de repetir.
Se o controle de limite estiver indisponível, a API não deixa a requisição passar: responde 429 com o código rate_limit_unavailable e Retry-After: 1. Espere e repita.
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.