# Consulta de CPF grátis por API: limites e restrições que você precisa saber > Conheça os limites e restrições de APIs gratuitas de consulta de CPF. Saiba o que esperar em termos de volume, rate limit, SLA e suporte. **Publicado:** 06/09/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/consulta-de-cpf-gratis-por-api-limites-e-restricoes-que-voce-precisa-saber --- APIs gratuitas de consulta de CPF são uma porta de entrada acessível para empresas e desenvolvedores que precisam validar dados cadastrais sem investimento inicial. No entanto, todo plano gratuito vem com limitações que precisam ser compreendidas antes da integração — ignorá-las pode levar a falhas em produção e degradação da experiência do usuário. ## Introdução APIs gratuitas de consulta de CPF são amplamente usadas para validações pontuais e projetos em fase inicial. Entender suas restrições de volume, rate limit, SLA e suporte é fundamental para planejar uma integração que funcione sem surpresas em produção. --- ## Limite de consultas mensais A restrição mais óbvia de qualquer free tier é o número máximo de consultas permitidas por mês. Na CPFHub.io, o plano gratuito oferece **50 consultas por mês**. Ao atingir esse limite, novas requisições não são bloqueadas: a API continua respondendo e cobra R$0,15 por consulta adicional. O que acontece quando o limite é atingido: * A API continua funcionando normalmente — não há interrupção do serviço. * Cada consulta excedente é cobrada a R$0,15, conforme os termos do plano. * É possível acompanhar o consumo em tempo real no dashboard da CPFHub.io (app.cpfhub.io). Para monitorar o consumo, o dashboard da CPFHub.io (app.cpfhub.io) exibe o número de consultas realizadas no mês corrente. --- ## Rate limit por requisição Além do limite mensal, existe o rate limit -- que controla a frequência com que você pode fazer requisições em um curto intervalo de tempo. Esse mecanismo protege a infraestrutura da API contra uso abusivo e garante estabilidade para todos os usuários. | Plano | Rate limit | | --- | --- | | Gratuito | 1 requisição a cada 2 segundos | | Pro | 1 requisição por segundo | | Corporativo | Personalizado | Na prática, se você tentar fazer duas consultas consecutivas em menos de 2 segundos no plano gratuito, a segunda poderá retornar um erro de throttling. A solução é implementar um controle de intervalo entre requisições. ### Exemplo de controle de rate limit em Node.js ```javascript const consultarCPF = async (cpf) => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpf}`, { method: 'GET', headers: { 'x-api-key': process.env.CPFHUB_API_KEY, 'Accept': 'application/json' }, signal: controller.signal } ); clearTimeout(timeoutId); return await response.json(); } catch (error) { clearTimeout(timeoutId); throw error; } }; ``` --- ## SLA e disponibilidade O SLA (Service Level Agreement) define o percentual mínimo de disponibilidade garantido pelo provedor. No caso da CPFHub.io: * **Plano Gratuito** -- SLA de 80%. * **Plano Pro** -- SLA de 99%. * **Plano Corporativo** -- SLA de 99,9%. Um SLA de 80% significa que, em um mês com 30 dias, o serviço pode ficar indisponível por até 6 dias sem violar o acordo. Para testes e validações pontuais, isso é aceitável. Para sistemas em produção que dependem da consulta em tempo real, um SLA mais alto é recomendado. Na prática, a infraestrutura da CPFHub.io mantém um uptime histórico de 99,9%, mas a garantia formal para o plano gratuito é menor do que a dos planos pagos. --- ## Suporte técnico limitado No plano gratuito, o suporte técnico geralmente se limita a: * **Documentação completa** -- com exemplos em mais de 13 linguagens. * **Status page** -- para verificar a disponibilidade do serviço em tempo real. * **Suporte por e-mail** -- com SLA de resposta conforme o plano. Nos planos pagos, o suporte é mais abrangente. O plano Pro inclui suporte via WhatsApp e e-mail com prioridade. O Corporativo adiciona gerente de conta dedicado, onboarding técnico assistido e suporte prioritário 24/7. --- ## Ausência de requisições em lote A API da CPFHub.io não suporta requisições em lote (batch). Cada CPF deve ser consultado individualmente, respeitando os rate limits do plano contratado. Isso significa que, para validar uma lista de CPFs, é necessário iterar sobre cada um e respeitar o intervalo mínimo entre requisições. ### Exemplo de consulta sequencial em Python ```python import requests import time cpfs = ["12345678900", "98765432100", "11122233344"] headers = { "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } resultados = [] for cpf in cpfs: url = f"https://api.cpfhub.io/cpf/{cpf}" try: response = requests.get(url, headers=headers, timeout=10) resultados.append(response.json()) except requests.exceptions.RequestException as e: resultados.append({"cpf": cpf, "error": str(e)}) # Respeitar rate limit do plano gratuito (1 req a cada 2s) time.sleep(2) for r in resultados: print(r) ``` --- ## Sem infraestrutura dedicada No plano gratuito, as requisições compartilham a infraestrutura com outros usuários do mesmo plano. Isso pode resultar em variações no tempo de resposta, especialmente em horários de pico. O tempo médio de resposta da CPFHub.io é de **~900ms**, mas em planos compartilhados pode haver variações. O plano Corporativo oferece infraestrutura exclusiva e escalável para operações que exigem performance consistente. --- ## Comparativo completo entre planos | Aspecto | Gratuito | Pro | Corporativo | | --- | --- | --- | --- | | Preço | R$ 0 | R$ 149/mês | Sob consulta | | Consultas/mês | 50 | 1.000 | Personalizado | | Consulta adicional | R$ 0,15 | R$ 0,15 | Personalizado | | Rate limit | 1 req/2s | 1 req/s | Personalizado | | SLA | 80% | 99% | 99,9% | | Suporte | Documentação e e-mail | WhatsApp e e-mail | 24/7 dedicado | | Infraestrutura | Compartilhada | Compartilhada | Exclusiva | | Desconto por volume | Não | Sim | Sim | --- ## Quando as limitações gratuitas se tornam um problema Os sinais de que é hora de migrar para um plano pago incluem: * O limite de 50 consultas é atingido antes da metade do mês. * Clientes reclamam de lentidão ou falhas no cadastro. * A operação depende da disponibilidade da API em horários comerciais. * O time de suporte precisa de respostas rápidas para resolver problemas de integração. A migração entre planos na CPFHub.io é simples e pode ser feita diretamente no painel de controle, sem necessidade de alterar o código da integração. A mesma chave de API funciona em todos os planos. --- ## Perguntas frequentes ### O plano gratuito da CPFHub.io bloqueia as consultas ao atingir 50 por mês? Não. Ao atingir o limite de 50 consultas mensais, a API continua respondendo normalmente — cada consulta excedente é cobrada a R$0,15, sem interrupção do serviço. Não há retorno de erro por limite de plano; o sistema simplesmente registra o excedente na fatura. ### Qual é a diferença prática entre o SLA do plano gratuito e o Pro? O plano gratuito garante 80% de disponibilidade mensal (o que equivale a até 6 dias de eventual indisponibilidade), enquanto o plano Pro garante 99%. Para sistemas em produção que dependem da consulta em tempo real durante cadastros ou transações financeiras, o plano Pro é a escolha recomendada. ### Como a CPFHub.io protege os dados de CPF consultados via API? A CPFHub.io adota boas práticas de segurança alinhadas à [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm), incluindo transmissão via HTTPS, autenticação por chave de API e logs de acesso auditáveis. O dado é tratado exclusivamente para a finalidade da consulta, sem compartilhamento com terceiros. ### Posso usar o plano gratuito em produção? Tecnicamente sim, mas com ressalvas. O SLA de 80% e o limite de 50 consultas mensais tornam o plano gratuito mais adequado para testes, desenvolvimento e MVPs. Para fluxos críticos de onboarding ou transações em produção, o plano Pro oferece SLA de 99% e 1.000 consultas mensais por R$149. ### Leia também - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de consulta de CPF: diferenças entre planos gratuito, Pro e Corporate](https://cpfhub.io/blog/api-de-consulta-de-cpf-diferencas-entre-planos-gratuito-pro-e-corporate) - [APIs de CPF: como avaliar o custo-benefício antes de contratar?](https://cpfhub.io/blog/apis-de-cpf-como-avaliar-o-custo-beneficio-antes-de-contratar) --- ## Conclusão Entender os limites e restrições de uma API gratuita de consulta de CPF é essencial para planejar sua integração de forma realista. O plano gratuito da [**CPFHub.io**](https://www.cpfhub.io/) é ideal para desenvolvimento, testes e projetos de baixo volume — mas ao crescer, a migração para o plano Pro é simples e não exige nenhuma alteração no código. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e entenda na prática quais limites se aplicam ao seu volume antes de escalar.