Limitações

A API Comercial atende até 500 requisições por minuto por assinatura. O limite vale para todos os endpoints autenticados e conta toda requisição, independentemente de a consulta ter encontrado o CNPJ.

A contagem usa uma janela deslizante de 60 segundos: não existe uma virada de minuto que zere o contador. Cada requisição deixa de contar 60 segundos depois de feita.

Além do limite da assinatura, existe um limite por IP, que soma as requisições de todas as assinaturas que chamam a API a partir do mesmo endereço. O limite por IP nunca é menor que o da sua assinatura: uma assinatura que chama a API sozinha a partir de um endereço atinge primeiro o próprio limite.

Ao ultrapassar qualquer um dos limites, a API responde com HTTP Status Code 429:

{
  "status": 429,
  "titulo": "Muitas requisições",
  "detalhes": "Excedido o limite máximo de 500 requisições por minuto por assinatura. Liberação ocorrerá em 13/10/2026, 11:47:12",
  "validacao": []
}

O horário de liberação vem apenas como texto dentro de detalhes, no fuso de Brasília. A resposta não traz o header Retry-After. Ao receber um 429, aguarde 60 segundos antes de tentar de novo e não interprete o texto de detalhes.

Boas práticas

• Controle o ritmo no seu lado. Distribua as chamadas ao longo do minuto em vez de dispará-las todas de uma vez.
• Limite a concorrência. Muitas requisições em paralelo esgotam o limite em segundos.
• Use backoff ao receber 429. Repetir a chamada imediatamente só prolonga o bloqueio.
• Evite consultas repetidas. Guarde no seu sistema o resultado de CNPJs já consultados.

Limite mensal

O limite por minuto é independente do limite de consultas mensais do plano contratado. Para acompanhar o consumo do período, use o endpoint de consumo.