← API de CNPJ ← Central de Ajuda

Rate limits, códigos HTTP e boas práticas de integração com a API

De 5.000 a 500.000 requisições/mês por plano. Códigos 200, 401, 403, 404, 429. Implemente retry, cache, throttling e circuit breakers.

Limites de Uso por Plano

Cada plano de assinatura possui limites específicos de requisições:

  • Plano Bronze: 20 requisições por minuto, 5.000 por mês
  • Plano Prata: 40 requisições por minuto, 12.500 por mês
  • Plano Ouro: 60 requisições por minuto, 50.000 por mês
  • Plano Diamante: 60 requisições por minuto, 200.000 por mês
  • Plano Black: 80 requisições por minuto, 500.000 por mês
  • Planos Customizados: Limites personalizados conforme contratado

Você pode monitorar seu uso atual na página de Tokens da API.

Códigos de Resposta HTTP

Ao fazer requisições, você receberá diferentes códigos HTTP:

  • 200 OK: Sucesso — dados da empresa retornados
  • 401 Unauthorized: Token inválido, expirado ou ausente
  • 403 Forbidden: Cota mensal excedida ou conta suspensa
  • 404 Not Found: CNPJ não encontrado na base de dados
  • 429 Too Many Requests: Limite de taxa excedido (requisições/minuto)
  • 500 Internal Server Error: Erro interno do servidor

Boas Práticas para Requisições

  1. Validação de CNPJ: Sempre valide o formato do CNPJ (14 dígitos numéricos) antes de fazer a requisição
  2. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro
  3. Timeout: Configure timeouts apropriados (recomendamos 30 segundos)
  4. Retry Logic: Implemente lógica de retry com backoff exponencial para erros 5xx
  5. Throttling: Respeite os limites de taxa implementando controle no seu lado
  6. Cache: Armazene respostas em cache quando apropriado para reduzir chamadas
  7. Monitoramento: Acompanhe seu uso mensal para evitar surpresas
  8. Circuit Breakers: Implemente circuit breakers para falhas consecutivas

Artigos relacionados

Última atualização: 2026-04-01

Perguntas Frequentes

Quando você ultrapassa o limite de requisições por minuto do seu plano, a API retorna o código HTTP 429 (Too Many Requests). Você deve aguardar antes de tentar novamente e implementar controle de taxa no seu lado para respeitar os limites. Use backoff exponencial para as novas tentativas.

Quando a cota mensal de requisições é esgotada, a API retorna o código HTTP 403 (Forbidden). Esse mesmo código é retornado quando a conta está suspensa. Para evitar interrupções, monitore seu uso mensal na página de tokens e considere um plano com cota maior se necessário.

Para erros 5xx (erro interno do servidor), implemente retry com backoff exponencial: aguarde 1 segundo antes da primeira tentativa, 2 segundos antes da segunda, 4 segundos antes da terceira e assim por diante. Limite o número máximo de tentativas (recomendamos 3) e registre os erros para monitoramento.

Circuit breaker é um padrão que monitora falhas consecutivas e, ao atingir um limite, interrompe temporariamente as tentativas para evitar sobrecarga. Quando a API estiver com instabilidade, o circuit breaker protege sua aplicação de ficarem em loop de erros, reduz requisições desnecessárias e melhora a resiliência geral da integração.

Quero Conhecer os Planos
Fale no Whatsapp