# Como garantir que sua API de CPF funcione com alta disponibilidade (SLA 99,9%) > Entenda como garantir alta disponibilidade ao integrar uma API de CPF. SLA, fallback, monitoramento e boas práticas para 99,9% de uptime. **Publicado:** 15/04/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-garantir-alta-disponibilidade-na-api-de-cpf --- Para operações críticas como onboarding, checkout e KYC, a API de consulta de CPF precisa estar disponível o tempo todo. Alta disponibilidade depende da combinação entre um provedor com SLA sólido e uma camada de resiliência na sua aplicação — com timeouts, retries, circuit breaker e fallback em cache. Sem essas práticas, uma instabilidade pontual pode travar cadastros, bloquear checkouts e comprometer operações de KYC. --- ## O que significa SLA 99,9% SLA (Service Level Agreement) é o compromisso de disponibilidade do provedor. Cada décimo percentual faz diferença quando se trata de sistemas em produção: | SLA | Downtime máximo/mês | Downtime máximo/ano | | --- | --- | --- | | 80% | 6 dias | 73 dias | | 99% | 7,3 horas | 3,65 dias | | 99,9% | 43 minutos | 8,7 horas | | 99,99% | 4,3 minutos | 52 minutos | A [**CPFHub.io**](https://www.cpfhub.io/) opera com SLA de 99,9% nos planos pagos, o que representa menos de 44 minutos de downtime possível por mês. Para sistemas que não podem parar, entender esse número é o primeiro passo para arquitetar uma integração resiliente. Consulte [o artigo sobre SLA de API de CPF](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) para ver o que exigir contratualmente do seu provedor. --- ## Boas práticas para alta disponibilidade ### 1. Implemente timeouts adequados Nunca faça chamadas sem timeout. Uma API travada pode travar toda a sua aplicação. ```python import requests def consultar_cpf(cpf: str) -> dict: url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } try: response = requests.get(url, headers=headers, timeout=5) response.raise_for_status() return response.json() except requests.Timeout: return {'error': 'Timeout', 'success': False} except requests.ConnectionError: return {'error': 'Conexao falhou', 'success': False} ``` ### 2. Implemente retry com backoff exponencial Falhas temporárias acontecem. Um retry inteligente resolve a maioria delas. ```python import time def consultar_com_retry(cpf: str, tentativas: int = 3) -> dict: for i in range(tentativas): resultado = consultar_cpf(cpf) if resultado.get('success') or resultado.get('error') is None: return resultado # Backoff exponencial: 1s, 2s, 4s time.sleep(2 ** i) return {'error': 'Maximo de tentativas excedido', 'success': False} ``` ### 3. Implemente circuit breaker Se a API estiver fora do ar, pare de enviar requisições por um período para evitar sobrecarga. ```python from datetime import datetime, timedelta class CircuitBreaker: def __init__(self, falhas_max=5, reset_apos=60): self.falhas = 0 self.falhas_max = falhas_max self.reset_apos = timedelta(seconds=reset_apos) self.aberto_em = None def pode_chamar(self) -> bool: if self.falhas < self.falhas_max: return True if datetime.now() - self.aberto_em > self.reset_apos: self.falhas = 0 return True return False def registrar_falha(self): self.falhas += 1 if self.falhas >= self.falhas_max: self.aberto_em = datetime.now() def registrar_sucesso(self): self.falhas = 0 ``` ### 4. Use cache como fallback Se a API estiver indisponível, retorne dados do cache (mesmo que não sejam os mais recentes) em vez de falhar completamente. ### 5. Monitore a disponibilidade * Configure health checks periódicos. * Use ferramentas como Grafana, Datadog ou UptimeRobot. * Configure alertas para latência alta ou erros HTTP 5xx. ### 6. Tenha um plano de degradação graceful Defina o que acontece quando a API está fora do ar: | Cenário | Ação | | --- | --- | | Cadastro | Aceitar provisoriamente, validar depois | | Checkout | Prosseguir com validação local (dígitos) | | KYC | Enfileirar para processamento posterior | --- ## Arquitetura resiliente ``` [Usuário] → [Sua Aplicação] → [Cache Local] ↓ (cache miss) [Circuit Breaker] ↓ (circuito fechado) [API CPFHub.io] ↓ (retry com backoff) [Resposta / Fallback] ``` --- ## Perguntas frequentes ### O SLA de 99,9% garante que a API nunca vai falhar? Não. Um SLA de 99,9% garante disponibilidade de pelo menos 99,9% do tempo, o que ainda permite até 43 minutos de downtime por mês. Por isso a integração precisa ter circuit breaker, retry e fallback em cache — para que sua aplicação funcione mesmo durante esses períodos. ### O que acontece se eu exceder o limite de consultas do meu plano? A API da CPFHub.io não bloqueia requisições quando o limite do plano é atingido. Cada consulta além da cota mensal é cobrada a R$0,15. Isso evita que sistemas em produção parem por causa de um pico de volume inesperado. ### Como monitorar a saúde da integração com a API de CPF em produção? Configure alertas para latência acima de 2 segundos e taxas de erro acima de 1%. Ferramentas como Datadog, Grafana ou o próprio [UptimeRobot](https://uptimerobot.com/) permitem criar health checks automáticos que disparam notificações antes que o problema afete os usuários finais. ### Qual o impacto de uma indisponibilidade da API de CPF em fluxos de KYC? Em fluxos de KYC, uma indisponibilidade sem plano de contingência pode bloquear completamente o onboarding de novos clientes. A recomendação é enfileirar as solicitações para processamento posterior — assim o usuário avança no cadastro e a validação é concluída assim que a API voltar a responder. ### Leia também - [SLA de API de CPF: entenda os níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como implementar circuit breaker em integrações com API de CPF](https://cpfhub.io/blog/como-implementar-circuit-breaker-integracoes-api-cpf) - [Como implementar retry com backoff exponencial em consultas de API de CPF](https://cpfhub.io/blog/como-implementar-retry-backoff-exponencial-consultas-api-cpf) - [Como implementar caching distribuído para consultas de CPF com Redis](https://cpfhub.io/blog/como-implementar-caching-distribuido-para-consultas-de-cpf-com-redis) --- ## Conclusão Alta disponibilidade na integração com API de CPF depende de duas coisas: um provedor confiável e uma integração resiliente. Timeouts, retries, circuit breaker e cache não são opcionais em sistemas de produção — são a diferença entre uma indisponibilidade transparente para o usuário e um incidente que bloqueia operações críticas. A [**CPFHub.io**](https://www.cpfhub.io/) foi projetada para ser o componente mais estável da sua stack de validação de identidade, com SLA de 99,9% nos planos pagos e latência média de ~900ms. Mas a responsabilidade pela resiliência da integração é compartilhada: use as práticas deste artigo para garantir que o seu sistema se recupere com elegância de qualquer instabilidade. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) e comece com 50 consultas gratuitas. Sem cartão de crédito.