Skip to main content

​
Como funciona

A API do Vistum aplica dois níveis de rate limit, combinados:

​
1. Limite por IP (pré-autenticação)

Antes mesmo de validar a chave, cada requisição está sujeita a um limite por IP que varia conforme o tipo de operação. Isso protege a infraestrutura contra força bruta e abuso.

​
2. Limite por API Key

Cada API Key tem seu próprio limite configurável (padrão 100 req/min, entre 1 e 1.000), definido na criação e editável em Configurações → Desenvolvedor → API Keys.

​
Perfis por tipo de operação

O limite por IP e o comportamento em falha do Redis dependem do verbo/operação:
Além do limite por IP, o limite da chave também se aplica. No perfil de envio, o teto é no máximo 15 mensagens/min por chave; no de envio a frio (mensagem para número novo, POST /api/v1/messages), o teto é 5 mensagens/min por chave — mesmo que o limite configurado da chave seja maior — porque cada envio a frio cria um contato e abre uma conversa nova.

​
Cap diário de números novos (cold outreach)

Além do rate limit por minuto, POST /api/v1/messages (mensagem para número novo) tem um cap diário por workspace: um teto de quantos números novos podem ser iniciados por dia, proporcional ao limite de disparo do plano, com piso de 200/dia. O contador só conta conversas novas — enviar para um número que já respondeu antes (conversa existente) não consome o cap. Ao atingir o teto, o envio retorna 429 COLD_LIMIT_REACHED e reinicia no dia seguinte.

​
Cota diária de mensagens

Enviar mensagens (tanto POST /api/v1/conversations/{id}/messages quanto POST /api/v1/messages) consome a cota diária de mensagens do plano, a mesma usada pelo chat humano: Ao atingir a cota, o envio retorna 429 MESSAGE_LIMIT_REACHED. A cota reinicia diariamente. Envios que falham no provedor não consomem a cota (é devolvida).

​
Headers de resposta

Toda resposta inclui headers com o estado do rate limit da chave:

​
Quando o limite é excedido

A API retorna 429 Too Many Requests com Retry-After (segundos). O code distingue a origem:

​
Boas práticas

  • Implemente retry com backoff exponencial em caso de 429
  • Monitore o header X-RateLimit-Remaining para antecipar throttling
  • Para volumes altos, use filas (BullMQ, n8n Queue, etc.) em vez de chamadas paralelas
  • Para envio de mensagens, respeite o teto do perfil (15/min por chave; 5/min no envio a frio), o cap diário de números novos e a cota diária do plano