Limites de taxa (rate limits) da API e cabeçalhos de cota

Para proteger a plataforma contra abusos e garantir bom desempenho para todos, cada organização tem um limite de requisições por minuto (rate limit) na API, de acordo com seu plano de assinatura. O limite se aplica por (usuário + organização) ou por token, dependendo de como você se autentica.

Limites por plano

Se sua organização usa um plano não reconhecido ou de teste, aplica-se um teto de segurança de 300 req/min.

Cabeçalhos de cota

Toda resposta bem-sucedida inclui:

• X-RateLimit-Limit: o teto do seu plano (requisições por minuto).
• X-RateLimit-Remaining: quantas requisições restam no minuto atual.

Quando você excede o limite, a API responde 429 Too Many Requests com:

• Retry-After: segundos que você deve esperar antes de tentar novamente.
• X-RateLimit-Reset: timestamp Unix em que sua cota é reiniciada.

Exemplo: lendo a cota restante

curl -i -X GET "https://app.omnifox.io/api/v1/contacts" \
  -H "Authorization: Bearer SEU_TOKEN" | grep -i ratelimit

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587

Dicas

• Se sua integração faz polling frequente (por exemplo, verificar mensagens novas), prefira processar Webhooks de saída em vez de consultar a API em intervalos curtos: consome muito menos cota.
• Projete seu cliente para respeitar o Retry-After com backoff exponencial em vez de tentar novamente de imediato.

Solução de problemas

• 429 constante mesmo com volume baixo: vários processos ou scripts podem estar compartilhando o mesmo usuário/token; todos consomem do mesmo bucket.
• Precisa de mais cota: faça upgrade do plano em Configurações > Plano e faturamento; o novo limite entra em vigor automaticamente no minuto seguinte.