# Timeout na API de CPF: como configurar e tratar corretamente > Aprenda a configurar e tratar timeouts corretamente ao consumir uma API de CPF. Exemplos em cURL, Python, JavaScript e Go. **Publicado:** 05/09/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/timeout-na-api-de-cpf-como-configurar-e-tratar-corretamente --- Para configurar timeout em consultas de CPF via API, defina um connection timeout de 5 segundos e um read timeout de 10 segundos — valores adequados para a latência média de ~900ms da CPFHub.io. Sem esses parâmetros, uma requisição travada pode bloquear threads indefinidamente e derrubar toda a aplicação. ## Introdução Quando uma aplicação faz requisições a APIs externas, o timeout é um dos parâmetros mais importantes -- e frequentemente negligenciados -- da integração. Uma requisição sem timeout definido pode manter threads bloqueadas indefinidamente, degradar a performance do sistema e, em cenários extremos, derrubar toda a aplicação. --- ## O que é timeout e por que ele importa O timeout define o tempo máximo que sua aplicação aguardará por uma resposta de uma API externa antes de desistir e tratar o erro. Sem essa configuração, uma requisição pode ficar pendente por minutos -- ou até indefinidamente -- caso a API esteja lenta ou indisponível. ### Tipos de timeout * **Connection timeout** -- Tempo máximo para estabelecer a conexão TCP com o servidor. Se o servidor estiver fora do ar ou inacessível, esse timeout evita a espera prolongada. * **Read timeout** -- Tempo máximo para receber a resposta completa após a conexão ser estabelecida. Se a API demorar para processar a requisição, esse timeout entra em ação. * **Total timeout** -- Soma do connection timeout e do read timeout, representando o tempo máximo total da operação. ### Valores recomendados para consultas de CPF A API da [**CPFHub.io**](https://www.cpfhub.io/) tem latência média de ~900ms, o que torna os valores abaixo adequados para a maioria dos cenários de produção. | Tipo | Valor recomendado | | --- | --- | | Connection timeout | 5 segundos | | Read timeout | 10 segundos | | Total timeout | 10-15 segundos | --- ## Configurando timeout em cURL ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" \ --connect-timeout 5 \ --max-time 10 ``` * `--connect-timeout 5` -- Define 5 segundos como tempo máximo para estabelecer a conexão. * `--max-time 10` -- Define 10 segundos como tempo máximo total da operação. --- ## Configurando timeout em Python A biblioteca `requests` aceita o parâmetro `timeout` como um número (total) ou como uma tupla (connection, read): ```python import requests def consultar_cpf(cpf): url = f"https://api.cpfhub.io/cpf/{cpf}" headers = { "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } try: # Timeout: (connection=5s, read=10s) response = requests.get(url, headers=headers, timeout=(5, 10)) response.raise_for_status() return response.json() except requests.exceptions.ConnectTimeout: print("Erro: não foi possível conectar ao servidor.") return None except requests.exceptions.ReadTimeout: print("Erro: o servidor demorou demais para responder.") return None except requests.exceptions.Timeout: print("Erro: timeout genérico na requisição.") return None except requests.exceptions.HTTPError as e: print(f"Erro HTTP: {e.response.status_code}") return None resultado = consultar_cpf("12345678900") if resultado: print(resultado) ``` O tratamento diferenciado entre `ConnectTimeout` e `ReadTimeout` permite que sua aplicação informe ao usuário exatamente o que aconteceu e tome ações distintas para cada cenário. --- ## Configurando timeout em JavaScript (Node.js) No Node.js com `fetch`, o timeout é implementado usando `AbortController`: ```javascript async function consultarCPF(cpf) { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpf}`, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, signal: controller.signal } ); clearTimeout(timeoutId); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { clearTimeout(timeoutId); if (error.name === 'AbortError') { console.error('Timeout: a requisição excedeu 10 segundos.'); return null; } console.error('Erro na requisição:', error.message); return null; } } ``` Se preferir usar `axios`, a configuração é mais direta: ```javascript const axios = require('axios'); async function consultarCPF(cpf) { try { const response = await axios.get( `https://api.cpfhub.io/cpf/${cpf}`, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, timeout: 10000 // 10 segundos } ); return response.data; } catch (error) { if (error.code === 'ECONNABORTED') { console.error('Timeout na requisição.'); } else { console.error('Erro:', error.message); } return null; } } ``` --- ## Configurando timeout em Go ```go package main import ( "context" "fmt" "io" "net/http" "time" ) func consultarCPF(cpf string) (string, error) { ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() url := fmt.Sprintf("https://api.cpfhub.io/cpf/%s", cpf) req, err := http.NewRequestWithContext(ctx, "GET", url, nil) if err != nil { return "", err } req.Header.Set("x-api-key", "SUA_CHAVE_DE_API") req.Header.Set("Accept", "application/json") client := &http.Client{ Timeout: 10 * time.Second, } resp, err := client.Do(req) if err != nil { if ctx.Err() == context.DeadlineExceeded { return "", fmt.Errorf("timeout: requisição excedeu 10 segundos") } return "", err } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { return "", err } return string(body), nil } func main() { resultado, err := consultarCPF("12345678900") if err != nil { fmt.Println("Erro:", err) return } fmt.Println(resultado) } ``` --- ## O que fazer quando o timeout ocorre Quando o timeout é atingido, sua aplicação precisa decidir o que fazer em seguida. Existem diferentes estratégias, cada uma adequada a um contexto: ### 1. Retry com backoff exponencial Tente novamente após intervalos crescentes. Por exemplo: 1 segundo, 2 segundos, 4 segundos. Isso é útil quando o timeout foi causado por uma instabilidade temporária. ### 2. Retornar erro amigável ao usuário Em aplicações web, informe ao usuário que houve um problema temporário e peça que tente novamente em alguns instantes. Evite exibir mensagens técnicas como "ECONNABORTED" ou "DeadlineExceeded". ### 3. Usar valor em cache Se a mesma consulta foi realizada recentemente e o resultado está em cache, retorne o valor cacheado em vez de falhar. Essa estratégia é especialmente útil em cenários de alta disponibilidade. ### 4. Registrar o incidente Independentemente da estratégia escolhida, registre o timeout em seus logs com informações como o CPF consultado, o horário e a duração antes do timeout. Esses dados ajudam a identificar padrões e ajustar os valores de timeout no futuro. --- ## Erros comuns ao configurar timeout * **Não definir timeout algum** -- O erro mais grave. Deixa a aplicação vulnerável a travamentos indefinidos. * **Timeout muito curto** -- Definir 1-2 segundos pode causar falhas frequentes em condições normais de rede, especialmente em APIs com tempo de resposta médio de 900ms. * **Timeout muito longo** -- Definir 60 segundos ou mais mantém threads bloqueadas por tempo excessivo, prejudicando a capacidade de processamento do servidor. * **Não diferenciar connection e read timeout** -- Um timeout de conexão pode ter valor menor (5s), enquanto o timeout de leitura pode ser mais generoso (10s). * **Não tratar a exceção de timeout** -- Capturar todas as exceções com um bloco genérico impede que o timeout seja identificado e tratado de forma específica. --- ## Perguntas frequentes ### O que é necessário para implementar validação de CPF neste contexto? A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### Como garantir conformidade com a LGPD ao usar uma API de CPF? Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### Quanto tempo leva para integrar a API CPFHub.io? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens. ### Leia também - [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 CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## Conclusão Configurar timeout corretamente é uma prática essencial em qualquer integração com APIs externas. No contexto de consultas de CPF, onde a resposta precisa ser rápida para não prejudicar a experiência do usuário, um timeout bem dimensionado garante que a aplicação se mantenha responsiva mesmo diante de problemas de rede ou indisponibilidade temporária. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a testar a configuração de timeout com dados reais em minutos.