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 tem latência média de ~900ms, o que torna os valores abaixo adequados para a maioria dos cenários de produção.

Configurando timeout em cURL

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):

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:

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:

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

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 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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a testar a configuração de timeout com dados reais em minutos.