Limites de taxa

Cada chave tem uma janela de 60 segundos (fixa quando o Redis está ativo, que é o caso normal; deslizante só no modo sem Redis). O limite por minuto segue o plano da própria chave. Ao ser excedida a API devolve 429 Too Many Requests. Além do limite por minuto, cada plano tem uma cota mensal de chamadas (tabela abaixo); esgotada, a API também devolve 429.

Plano	Req/min	Chamadas/mês	Lote (receptores)
Free	10	1.000	—
Starter	30	10.000	100
Pro	100	100.000	2.000
Business	300	1.000.000	5.000
Enterprise	1.000	10.000.000	10.000
Ultra	5.000	100.000.000	50.000
Carrier (Tier-1)	sob contrato	sob contrato	sob contrato

Tier Carrier (Tier-1 / operadoras nacionais). Quotas, throughput e SLA dimensionados por contrato. Só sob contrato, depois de uma PoC medida. Falar com vendas.

Headers de resposta

• X-RateLimit-Limit — teto de req/min vigente
• X-RateLimit-Remaining — quantas ainda cabem na janela
• Retry-After — presente nos 429 da cota mensal de chamadas, de IA e de cobertura, e nos da demo. O 429 do limite por minuto e o da cota de PDFs não o trazem

Chaves de demo

Cap adicional de 6 req/min independente do tier nominal da chave.

Cobrança de excedente (overage billing)

Quando o servidor tem OVERAGE_BILLING_ENABLED=true (por padrão está desligado), equipes (teams) com plano pago e stripe_customer_id configurado continuam a ser atendidas além da cota mensal em vez de receber 429 Too Many Requests. Cada unidade excedente é cobrada via fatura Stripe out-of-cycle, sem interromper o serviço.

Como ativar:

1. Servidor: a env OVERAGE_BILLING_ENABLED=true precisa estar setada (por padrão, false).
2. Time: precisa ter stripe_customer_id (criado automaticamente no primeiro checkout do plano).
3. Tarifa por unidade (configurável via STRIPE_OVERAGE_*_CENTS):

Métrica	Preço por unidade (BRL)
requests	R$ 0,01
pdfs	R$ 0,25
coverage_predict	R$ 0,10
ai	R$ 0,05

Sinalização na resposta:

Quando uma request foi atendida em modo de excedente (acima da cota), a resposta carrega:

X-Overage-Billing: true
X-Quota-Used: 1001
X-Quota-Limit: 1000

Seu SDK pode usar esse header para alertar o operador de que aquela chamada será faturada. Quando o time não está habilitado para overage, o comportamento padrão (429) é preservado.

Para desativar overage para um time específico, remova o stripe_customer_id no portal Admin ou via PATCH /teams/{id} (cache de elegibilidade expira em 60 s).