Janela deslizante de 60 segundos por IP, API Key e plano contratado.
Documentação API
Limites de uso da API CNPJ
A API CNPJ utiliza políticas de Rate Limit para garantir disponibilidade e estabilidade durante consultas de CNPJ, busca de empresas e integração via API REST. Os limites variam conforme o plano contratado, e API REST e MCP compartilham a janela do mesmo token.
Quando o limite é excedido, a API retorna Too Many Requests com orientação de retry.
Use os headers de resposta para acompanhar limite, restante e reset em tempo real.
Estabilidade
Por que existe limite de requisições?
O limite de requisições protege a infraestrutura da API, evita abuso e garante desempenho consistente para todos os clientes que consultam CNPJ, buscam empresas, integram CRMs, ERPs, marketplaces, agentes MCP e sistemas internos. A API utiliza controles de janela deslizante e Token Bucket para permitir pequenos picos de uso sem comprometer a estabilidade.
Starter
3
req/min
- Sem token: 3 req/min por IP
- Com token Starter: 3 req/min
- O plano Starter permite realizar até 3 consultas de CNPJ, buscas de empresas ou chamadas MCP por minuto.
- 10 mil consultas e buscas por mês
- API e MCP compartilham o consumo do token
Mais Popular
Basic
20
req/min
- O plano Basic permite até 20 requisições por minuto em endpoints da API REST e MCP.
- 100 mil consultas e buscas por mês
- Empresas relacionadas e webhooks
- Primeira integração com API REST e MCP
Pro
100
req/min
- O plano Pro permite até 100 requisições por minuto para operações comerciais, CRM, ERP e prospecção B2B.
- 500 mil consultas e buscas por mês
- Exportação CSV/PDF
- Suporte prioritário
Business
250
req/min
- O plano Business permite até 250 requisições por minuto para equipes de SDR, vendas B2B e integrações de maior volume.
- 1 milhão de consultas e buscas por mês
- Exportação CSV/XLSX/PDF
- Escala intermediária antes do Enterprise
Enterprise
500
req/min
- O plano Enterprise permite até 500 requisições por minuto para SaaS, marketplaces e operações de alto volume.
- 2 milhões de consultas e buscas por mês
- Exportação CSV/XLSX/PDF
- Operação comercial de alto volume
Como gerenciamos o abuso
Nossos limites são calculados em janelas deslizantes de 60 segundos por IP, usuário ou API Key. A política vale para endpoints de consulta de CNPJ, busca de empresas, API REST e MCP. Se você exceder o limite receberá erro 429.
Token Bucket permite pequenos picos temporários, mas a janela total continua limitada pelo plano para manter previsibilidade.
Boas Práticas
- 1Cache de respostas
Armazene respostas por 24h para reduzir consultas repetidas de CNPJ e empresas.
- 2Consultas em lote
Use endpoint /bulk quando precisar validar vários CNPJs dentro de uma operação controlada.
429 Too Many RequestsExcesso de Requisições
{
"error": "rate_limit_exceeded",
"message": "Você atingiu o limite de requisições por minuto do seu plano.",
"retry_after": 45
}Headers de Resposta
Use estes headers para monitorar seu consumo em tempo real:
X-RateLimit-Limit20Limite máximo permitido para o IP, token ou plano na janela atual.
X-RateLimit-Remaining2Quantidade de requisições restantes antes de receber erro 429.
X-RateLimit-Reset1704428000Timestamp Unix em segundos indicando quando a janela será renovada.
Regras Avançadas e Otimização
Cache Inteligente
Implemente Redis ou Memcached para reduzir requisições.
Janela Deslizante
Utilizamos Rolling Window de 60 segundos para medir consumo de forma contínua.
Burst Allowance
Token Bucket permite picos temporários de até 10 requisições simultâneas sem perder controle da janela.
Segurança por IP
Sem token: limite de 3 req/min por IP. Com token, o limite segue o plano: Starter 3, Basic 20, Pro 100, Business 250 e Enterprise 500 req/min. API e MCP usam o mesmo token.
CORS
Pre-flight OPTIONS não contam no rate limit.
User-Agent
Obrigatório envio de User-Agent descritivo.
FAQ técnico
Perguntas frequentes sobre rate limit, erro 429 e consumo da API
O que acontece quando atinjo o limite?
A API retorna HTTP 429 Too Many Requests com retry_after e headers X-RateLimit para indicar quando tentar novamente.
Como evitar erro 429?
Use cache, fila de processamento, retentativas com backoff, leitura dos headers X-RateLimit e chamadas em lote quando disponível.
O cache reduz o consumo?
Sim. Cachear respostas por 24 horas reduz chamadas repetidas de consulta CNPJ, busca de empresas e enriquecimento cadastral.
Como funciona o Token Bucket?
O algoritmo Token Bucket controla a taxa de requisições e permite pequenos picos de uso sem comprometer a estabilidade da API.
O limite depende do plano?
Sim. Sem token o limite é público por IP. Com API Key, o limite segue o plano contratado e é compartilhado entre API REST e MCP.
Posso aumentar o limite?
Sim. Você pode migrar de plano ou contratar Enterprise para volumes maiores e regras sob medida.
O endpoint /bulk possui limite diferente?
Endpoints em lote podem ter regras próprias de quantidade por chamada, mas ainda contam dentro da janela de consumo do token.