Docs
Páginas desta seção

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 chamaLimiteContado por
Token de login500 por minutoUsuário do token
Chave de integração (wsk_, só na API /v1)600 por minutoChave
Sem token válido1.200 por minutoEndereç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çalhoValor
X-RateLimit-LimitRequisições aceitas na janela
X-RateLimit-RemainingQuantas ainda cabem na janela
X-RateLimit-ResetSegundos 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
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:

RotaLimiteContado por
POST /auth/login100 por minutoEndereço IP
POST /auth/forgot-password3 por horaEndereço IP
POST /auth/reset-password3 por horaEndereço IP
POST /medias e POST /leads/imports10 por segundoEndereço IP
POST /whatsapp/business-phones/{id}/request-verification e POST /whatsapp/business-phones/{id}/verify-code5 por diaEndereço IP
GET /cep/search20 por minutoEndereço IP
POST /webhooks/workflow/{token} (gatilho de fluxo)120 por minutoEndereç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:

LimiteValor
Por chave de API600 requisições por minuto
Por endereço IP de origem1.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:

json
{
  "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.