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:

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:

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

Did this page help you?