Introdução: por que timeouts via proxy merecem uma conversa à parte

Imagine a cena: seu scraper está rodando há três dias, consumindo tráfego de proxies móveis, e na saída — metade dos registros vazios e logs lotados de palavras como timeout, connection reset e remote end closed connection. Soa familiar? Já vimos dezenas de sistemas assim, e quase sempre a raiz do problema é uma só: timeouts configurados "no olhômetro" — um número mágico tipo 30 segundos para tudo de uma vez. Em conexão direta isso até funciona. Via proxy, especialmente móvel, já não funciona mais.

O motivo é que o proxy adiciona mais um trecho de rede na cadeia, mais um conjunto de filas e mais um nó que tem seus próprios timeouts. A requisição não passa por uma única fase de espera, mas por cinco ou seis, e em cada uma dá para "travar" por motivos diferentes. Um limite único não distingue onde exatamente você ficou preso: no handshake TCP com o proxy, no estabelecimento do túnel até o site de destino, no primeiro byte lento da resposta ou na transmissão de um corpo grande.

Este artigo é sobre arquitetura de espera. Vamos destrinchar de quais fases se compõe uma requisição HTTP via proxy, qual timeout responde por cada fase, o que acontece fisicamente quando ele dispara e como montar, a partir de limites separados, um orçamento total coerente. Vale já deixar claro o que está fora de escopo: aqui nós não discutimos códigos de resposta 429 ou 503 nem estratégias de retry com backoff exponencial. Essa é uma camada separada — reação ao que o servidor já respondeu. Aqui falamos de situações em que não há resposta nenhuma, e de quanto tempo estamos dispostos a esperar por ela em cada nível.

Depois da leitura, você vai conseguir: decompor qualquer requisição em fases e atribuir um limite a cada uma; explicar por que o cliente mostrou timeout e mesmo assim o servidor executou a ação; alinhar corretamente os timeouts do cliente, do pool de conexões e do próprio proxy; e, principalmente, parar de perder dados e dinheiro em esperas inúteis.

Fundamentos: o que é timeout e de quais fases se compõe uma requisição

Timeout como contrato de espera

Timeout é o tempo máximo que o cliente aceita esperar pela ocorrência de um determinado evento antes de considerar a tentativa fracassada e liberar recursos. A palavra-chave aqui é determinado. Não existe isso de "timeout da requisição em geral". Existe timeout para estabelecer conexão TCP, timeout para o handshake TLS, timeout para esperar dados do socket, timeout para escrever no socket, timeout para aguardar uma conexão livre no pool e, por fim, o prazo total da operação.

Uma boa analogia é uma viagem com baldeações. Você tem tempo para chegar à rodoviária, tempo de espera pelo ônibus, tempo de viagem, tempo de conexão. E tem o limite geral: às nove da manhã você precisa estar na reunião. Se você controla só o limite geral, só descobre o problema quando já se atrasou. Se controla cada etapa, consegue decidir antes: pegar um táxi, por exemplo, porque o ônibus não veio em dez minutos.

Fases de uma requisição HTTP em conexão direta

Mesmo sem proxy, a requisição é uma sequência de passos:

  1. Resolução de nome (DNS). O cliente converte o domínio em endereço IP. Normalmente leva de unidades a centenas de milissegundos, mas com problemas no resolver pode travar por segundos.
  2. Conexão TCP. Handshake de três vias: SYN, SYN-ACK, ACK. Exige uma ida e volta completa (RTT) até o servidor.
  3. Handshake TLS para HTTPS. Mais uma ou duas idas e voltas, dependendo da versão do protocolo.
  4. Envio da requisição (write). Cabeçalhos e corpo são escritos no socket. Para requisições pequenas é instantâneo, para upload de arquivos leva tempo perceptível.
  5. Espera pelo primeiro byte da resposta (TTFB). O servidor pensa: executa consultas ao banco, renderiza a página, chama seus microsserviços.
  6. Leitura do corpo da resposta (read). Os dados chegam em pedaços; entre um pedaço e outro pode haver pausas.

O que o proxy adiciona

O proxy quebra essa cadeia em duas partes. O cliente estabelece conexão com o servidor proxy, e o proxy é quem estabelece conexão com o nó de destino. Para HTTPS sobre proxy HTTP usa-se o método CONNECT: o cliente pede ao proxy para abrir um túnel TCP até o host e a porta, o proxy responde com status 200, e só depois o cliente inicia o handshake TLS já com o servidor de destino através do túnel. Para SOCKS5 a lógica é análoga: existe a fase de saudação e autenticação com o proxy, depois o comando de estabelecer conexão com o destino, depois a espera pela confirmação.

O resultado é uma lista ampliada de fases:

  1. Resolução DNS do endereço do proxy (se estiver definido por domínio).
  2. Conexão TCP com o proxy.
  3. Autenticação e comando de estabelecer túnel (CONNECT ou requisição SOCKS).
  4. Espera enquanto o proxy resolve o nome do host de destino e estabelece conexão TCP com ele — essa fase acontece do lado do proxy, mas o cliente a aguarda.
  5. Handshake TLS com o servidor de destino através do túnel.
  6. Envio da requisição HTTP.
  7. Espera pelo primeiro byte da resposta.
  8. Leitura do corpo.

Repare no quarto item. É exatamente aí que mora a maior armadilha dos proxies móveis. O servidor proxy em si geralmente fica em um data center, e a conexão TCP até ele é estabelecida em dezenas de milissegundos. Mas dali o tráfego segue por um modem celular, onde o RTT fica entre 40 e 120 milissegundos e, com a estação base congestionada, dispara para meio segundo ou mais. A resolução de nome e o handshake com o destino nesse trecho facilmente consomem um ou dois segundos. Um cliente que considera "connect timeout" apenas até o proxy vai achar que a conexão foi estabelecida instantaneamente, e depois vai empacar numa espera inexplicável no passo seguinte.

Mergulho profundo: o que acontece fisicamente quando cada timeout dispara

Configurar o número é metade do trabalho. Bem mais importante é entender em que estado o sistema fica depois que o limite disparou. Vamos por fase.

Disparo do connect timeout

O cliente enviou o SYN e não recebeu SYN-ACK dentro do tempo estipulado. O sistema operacional, por conta própria, retransmite o SYN de forma exponencial: 1, 2, 4, 8 segundos e assim por diante, somando até 60–120 segundos por padrão nos kernels mais usados. O seu connect timeout interrompe essa espera antes. O socket é fechado, nenhum dado foi enviado ao servidor, o estado do lado remoto não mudou. Esse é o tipo mais seguro de timeout: repetir a tentativa não traz risco à idempotência.

Via proxy a imagem fica um pouco mais complexa. Se o TCP até o proxy foi estabelecido e a fase CONNECT travou, o cliente já enviou o comando ao proxy e aguarda o status. Ao disparar, o cliente fecha o socket com o proxy. O proxy percebe o fechamento e, em regra, aborta sua tentativa de conectar ao destino. Mas nem sempre na hora: algumas implementações primeiro esperam seu próprio timeout de upstream e só depois liberam recursos. Para o cliente isso é invisível, mas no servidor proxy vão se acumulando conexões semiabertas, o que sob carga massiva reduz a capacidade dele.

Detalhe importante: em bibliotecas clientes diferentes, a fase CONNECT é contabilizada de formas distintas. Em umas, ela cai sob o connect timeout; em outras, não é coberta por nada além do prazo total da requisição. Se você não tem prazo total e o CONNECT travou, a requisição pode ficar pendurada indefinidamente. Testar isso é fácil: aponte o cliente para um proxy que aceita TCP mas não responde ao CONNECT (um servidor TCP comum sem lógica serve como esse tipo de dublê) e veja em quantos segundos o cliente desiste.

Disparo do TLS handshake timeout

O túnel TCP via proxy está aberto, o cliente enviou o ClientHello e o ServerHello não chegou. Motivos: canal do modem lento, perda de pacote no trecho móvel, servidor de destino sobrecarregado que aceita TCP mas não consegue processar o TLS. Ao disparar, o socket é fechado, a requisição HTTP ainda não foi enviada, o estado no servidor não mudou. Também é seguro para retry.

Observação prática: em canais móveis o handshake TLS costuma ser um ponto frequente de atraso, porque exige várias idas e voltas consecutivas, e cada pacote perdido acrescenta um segundo de retransmissão. Com a migração para o TLS 1.3 o número de idas e voltas diminuiu, o que reduziu sensivelmente a incidência desses timeouts.

Disparo do write timeout

O cliente escreve o corpo da requisição no socket, mas o buffer de envio está cheio e não libera: o lado remoto não lê nem confirma o recebimento. Quando dispara, parte dos dados já pode ter chegado ao servidor. Se for upload de arquivo ou envio de formulário, o servidor pode ter recebido um fragmento. Em geral, um corpo incompleto gera erro de parsing do lado do servidor, mas em protocolos de streaming e uploads multipart as consequências dependem da implementação. Repetir essa requisição exige cuidado.

Disparo do read timeout

Aqui começa a parte mais interessante e mais perigosa. A requisição foi enviada por completo. O cliente aguarda dados, e eles não chegam no intervalo estipulado. O cliente fecha o socket e lança exceção. Mas o que acontece do outro lado?

O proxy percebe que o cliente fechou a conexão. Um bom proxy, nesse momento, fecha também a conexão upstream com o servidor de destino. Mas o servidor de destino já recebeu a requisição e já está processando. Se for um POST que cria um pedido, debita saldo ou envia mensagem, a ação com grande probabilidade será executada. O servidor só vai saber da queda quando tentar escrever a resposta e receber um erro. Nesse momento, a transação no banco já foi concluída faz tempo.

Essa é uma propriedade fundamental do read timeout: ele diz que você não esperou o suficiente pela resposta, mas não diz nada sobre se a ação foi executada. Por isso, para operações não idempotentes o read timeout deve ser tratado de forma diferente do connect timeout, e por isso APIs sérias exigem chaves de idempotência.

Outro detalhe — onde exatamente você travou. O read timeout dispara tanto na espera pelo primeiro byte (o servidor pensando) quanto numa pausa entre pedaços do corpo (o servidor entregando dados em fluxo com atrasos). Muitas bibliotecas tratam o read timeout como intervalo de inatividade entre duas leituras bem-sucedidas do socket, e não como tempo total de leitura. Isso significa que uma resposta de centenas de megabytes chegando a um kilobyte por segundo nunca vai disparar um read timeout de 10 segundos — afinal, os dados chegam regularmente. Sem prazo total, essa requisição pode ficar pendurada por horas.

O que o proxy vê e o que devolve

O proxy tem seus próprios timeouts, e eles geram sintomas diferentes. Se o proxy não conseguiu conectar ao destino dentro do seu limite, ele devolve ao cliente uma resposta ao CONNECT com status 502 ou 504 — e, do ponto de vista do cliente, isso não é timeout, é erro de proxy. Se o proxy esperou resposta do destino e não a recebeu, ele também pode devolver 504 Gateway Timeout já dentro da resposta HTTP (para HTTP comum sem túnel). E se o proxy tem um limite de inatividade no túnel e ele disparou, o cliente vai ver uma queda súbita da conexão — connection reset ou resposta vazia — sem timeout algum do seu lado.

Daí a regra: o timeout do cliente deve estar alinhado com os timeouts do proxy. Se o proxy derruba o túnel após 60 segundos de inatividade e o seu read timeout é de 90 segundos, você nunca vai ver timeout — vai ver quedas misteriosas. Se o proxy dá 30 segundos para conectar ao destino e o seu limite nessa fase é de 10 segundos, você vai desistir antes e nem saber que o proxy poderia ter conseguido.

Método 1: configurar o connect timeout considerando dois hops

Teoria: o que cobre e o que deveria cobrir

O connect timeout limita o estabelecimento da conexão de transporte. Via proxy, isso coloca a pergunta: conexão com quem? Formalmente — com o proxy. Na prática — nos importa quando teremos um túnel pronto até o destino. Por isso recomendamos pensar em dois limites separados, mesmo que a biblioteca ofereça um único parâmetro.

Limite do primeiro hop — TCP até o servidor proxy. O proxy fica em data center, o RTT até ele é estável. Referência: 5–8 RTTs, mas nunca menos que 2 segundos nem mais que 5. Se o proxy não responde ao SYN em 3 segundos, ou está sobrecarregado ou está fora do ar, e esperar mais é inútil; melhor trocar para outro endereço do pool.

Limite do segundo hop — tempo entre enviar o CONNECT e receber o status 200. Aqui entra o canal móvel. A referência depende de onde está o destino e da qualidade da rede celular: tipicamente 3–10 segundos. Observamos que o percentil 95 do tempo de estabelecimento de túnel via LTE para sites populares fica entre 1,5 e 2,5 segundos, e o percentil 99 entre 4 e 6 segundos. Definir um limite abaixo do percentil 99 significa perder uma requisição em cada cem por iniciativa própria.

Como medir seus valores

  1. Junte uma amostra de pelo menos 500 requisições via seu proxy para os hosts de destino em horários variados do dia.
  2. Registre separadamente o tempo até estabelecer o TCP com o proxy, o tempo até a resposta ao CONNECT e o tempo do handshake TLS. A maioria dos clientes consegue fornecer essas métricas: no curl são as variáveis time_connect e time_appconnect, no Go são os hooks do httptrace, nos clientes Python são eventos de tracing ou medições em volta das fases.
  3. Monte a distribuição. Interessam p50, p95, p99 e o máximo.
  4. Defina o limite no p99 mais uma folga de 30–50 por cento. Não no máximo — outliers sempre existem, e ajustar-se a eles significa manter recursos para anomalias pontuais.
  5. Revise a cada trimestre ou quando mudar operadora, região ou plano do proxy.

Prática em clientes diferentes

Na biblioteca Python requests o timeout é definido por uma tupla, onde o primeiro valor é connect e o segundo é read. Via proxy, o primeiro valor cobre o TCP até o proxy e, em regra, a espera pela resposta ao CONNECT, já que o túnel é estabelecido no mesmo socket com o mesmo limite. Exemplo:

resp = session.get(url, proxies=proxies, timeout=(5, 20))

No httpx existe um objeto Timeout dedicado com quatro campos: connect, read, write e pool. É o modelo mais claro entre os clientes Python:

timeout = httpx.Timeout(connect=5.0, read=20.0, write=10.0, pool=3.0)

No curl há duas flags-chave: --connect-timeout define o limite de estabelecimento da conexão, incluindo CONNECT e TLS, e --max-time define o teto total. No Go o timeout de estabelecimento TCP é definido via Dialer no Transport, o TLS via TLSHandshakeTimeout, e a fase CONNECT é limitada pelo contexto da requisição. No Java HttpClient o connectTimeout é configurado no builder do cliente, e o limite da requisição vai na própria requisição. No Node.js via undici existem connectTimeout, headersTimeout e bodyTimeout, além do AbortSignal para o prazo total.

Checklist do connect timeout

  • Valor nunca menor que 2 nem maior que 10 segundos para proxy de data center e móvel, respectivamente.
  • Você sabe com certeza se o seu cliente cobre a fase CONNECT com esse limite.
  • Ao disparar, você troca para outro proxy do pool em vez de insistir no mesmo.
  • Você considera que o SO retransmite o SYN sozinho — seu limite deve ser mais curto que o do sistema.
  • Para hosts IPv6 está ativo o fallback para IPv4 (Happy Eyeballs), senão um caminho IPv6 ruim consome todo o limite.

Método 2: read timeout como intervalo de inatividade e proteção do primeiro byte

Duas tarefas diferentes sob o mesmo nome

O read timeout resolve duas tarefas, e é útil separá-las mentalmente, mesmo que a biblioteca ofereça um único parâmetro.

Espera pelo primeiro byte. É o tempo de trabalho do servidor sobre a sua requisição. Para páginas estáticas, dezenas de milissegundos. Para resultados de busca de marketplace com filtros, de meio segundo a alguns segundos. Para APIs de relatórios pesados, dezenas de segundos. Via proxy móvel, soma-se a isso a latência do canal no caminho de volta.

Pausa entre pedaços do corpo. O servidor já está entregando dados, mas com intervalos: gera a página em partes, faz streaming de resultado ou simplesmente esbarra num canal estreito. Aqui o que importa não é o tamanho total, e sim o silêncio máximo.

Alguns clientes têm parâmetros separados. No Go existe ResponseHeaderTimeout para o primeiro byte dos cabeçalhos e mecanismos próprios para o corpo. No undici, headersTimeout e bodyTimeout. Na maioria dos clientes Python, um único read timeout funciona como intervalo de inatividade em qualquer etapa da leitura.

Como escolher o valor

  1. Determine a natureza das respostas de destino. Uma página HTML e um JSON em streaming exigem limites diferentes.
  2. Meça o TTFB através do seu proxy. Pegue o p99 e multiplique por 1,5. Para scraping web típico via canal móvel, dá 8–15 segundos.
  3. Meça a pausa máxima entre chunks numa amostra de respostas bem-sucedidas. Costuma ser bem menor que o TTFB: 1–3 segundos. Se o cliente permitir, defina o bodyTimeout separadamente e mais rígido.
  4. Nunca conte com o read timeout como proteção contra entrega lenta. Para isso existe o prazo total (Método 4).

O que fazer quando dispara

Aqui surge a pergunta central: pode repetir? A resposta depende do método e da semântica:

  • GET, HEAD, OPTIONS — pode repetir, o estado do servidor não mudou (a menos que o site desrespeite a semântica do protocolo).
  • PUT com corpo completo, DELETE — formalmente idempotentes, repetir é seguro.
  • POST sem chave de idempotência — repetir pode criar duplicata. Reação correta: não repetir às cegas, mas antes verificar o estado com outra requisição ou marcar a operação como "resultado desconhecido" para conferência posterior.
  • POST com chave de idempotência — pode repetir com segurança, o servidor devolverá o resultado da primeira execução.

Recomendamos enfaticamente diferenciar nos logs e métricas read timeout antes do primeiro byte e read timeout no meio do corpo. O primeiro costuma indicar sobrecarga do servidor de destino ou do proxy; o segundo, problemas de canal. Os tratamentos são distintos: no primeiro caso, ajuda reduzir o paralelismo; no segundo, trocar de proxy ou de região.

Particularidade dos canais móveis

A rede celular opera com latência variável. O modem pode "congelar" por um ou dois segundos durante a troca de setores da estação base ou ao sair do modo de economia de energia. Do ponto de vista do cliente, isso aparece como silêncio no socket. Se o seu read timeout é de 2 segundos, você vai pegar falsos positivos várias vezes por hora em cada modem. Observamos que subir o limite de 3 para 6 segundos reduziu a incidência de timeouts em proxies móveis de 4 a 5 vezes, sem aumento perceptível no tempo médio das requisições. Segundos de ociosidade em requisições raras custam menos que requisições repetidas e tráfego desperdiçado.

Checklist do read timeout

  • Valor baseado no p99 de TTFB medido via seu proxy, e não na intuição.
  • Você entende que o limite é um intervalo de inatividade, não o tempo total de leitura.
  • Para requisições não idempotentes não há retry automático sem verificação quando o limite dispara.
  • Nas métricas, timeouts antes do primeiro byte e dentro do corpo estão separados.
  • O valor é menor que o idle timeout do túnel do lado do proxy.

Método 3: write timeout e trabalho com corpos de requisição grandes

Quando a escrita pode travar

Para a maioria das requisições, o corpo cabe num único segmento TCP e vai embora na hora — a escrita termina antes mesmo de os dados saírem fisicamente da máquina. O write timeout ganha relevância em três casos: upload de arquivos, envio de arrays JSON grandes e qualquer transmissão por canal estreito. Proxy móvel é exatamente esse canal na direção de saída: a velocidade típica de upload de um modem é bem menor que a de download, e os buffers nos nós intermediários são limitados.

A mecânica é esta: o cliente chama a escrita, os dados caem no buffer de envio do socket, o kernel os envia em pedaços conforme recebe confirmações. Se as confirmações não chegam, o buffer enche e a próxima escrita bloqueia. O write timeout limita o tempo desse bloqueio.

Três estratégias para corpos grandes

Estratégia A: limite total de escrita. Abordagem simples: um write timeout para toda a requisição. Serve para corpos de até alguns megabytes. O valor é escolhido a partir de uma estimativa: tamanho do corpo dividido pela velocidade mínima aceitável, mais folga. Por exemplo, 5 megabytes a uma velocidade mínima de 500 kilobytes por segundo — 10 segundos, com folga, 15.

Estratégia B: limite por pedaço. O cliente escreve o corpo em chunks e limita o tempo de cada escrita. É assim que funciona a maioria dos clientes assíncronos: ali, write timeout significa a pausa máxima no envio de um pedaço. Valor: 3–10 segundos, independentemente do tamanho do arquivo. A proteção contra entrega lenta recai inteiramente sobre o prazo total.

Estratégia C: controle de velocidade. O cliente acompanha a velocidade real de envio e interrompe a requisição se ela cair abaixo de um limiar por N segundos. No curl, para isso existem o par de flags --speed-limit e --speed-time. É a ferramenta mais precisa: distingue "lento, mas andando" de "travado".

O que acontece quando dispara

Parte do corpo já está no servidor. Se você fez upload de arquivo numa única requisição, o servidor vai receber um corpo truncado. Em protocolo multipart isso geralmente gera erro de parsing e recusa total, o que é seguro. Para APIs com suporte a uploads retomáveis (tus, protocolos em chunks de storages em nuvem), a reação correta é pedir ao servidor o offset e continuar dali. É justamente uploads retomáveis que recomendamos para qualquer corpo acima de 10 megabytes via proxy móvel: uma requisição longa única por canal celular é vulnerável demais a quedas.

Configuração passo a passo para uploads via proxy

  1. Estime a velocidade mediana e a mínima de upload via seu proxy. Envie um arquivo de teste de 5–10 megabytes vinte vezes em horários variados.
  2. Se a variação de velocidade for maior que três vezes, use a Estratégia B ou C, não o limite total.
  3. Divida arquivos grandes em partes de 1–5 megabytes, se o serviço de destino suportar.
  4. Defina o write timeout por pedaço em 5–10 segundos.
  5. Complemente obrigatoriamente com um prazo total para a requisição inteira, calculado a partir do tamanho e da velocidade mínima.
  6. Ao disparar, determine exatamente o que o servidor conseguiu receber, em vez de repetir tudo do zero.

Método 4: orçamento total da requisição e propagação do deadline

Por que a soma dos limites parciais ainda não é um orçamento

Digamos que você configurou connect 5, TLS 5, write 10, read 15 segundos. Parece que a requisição não pode durar mais que 35 segundos. Mas o read timeout é intervalo de inatividade. Uma resposta que chega a um kilobyte a cada 14 segundos nunca vai violá-lo. Uma requisição de 10 megabytes nesse ritmo levaria quase um dia. Sem um limite total, seus workers ficam ocupados indefinidamente, o pool de conexões se esgota e o sistema para — mesmo que nenhum timeout parcial tenha disparado.

Orçamento total (deadline, total timeout) é o teto absoluto para toda a operação, da primeira chamada de sistema ao último byte lido. Ele não substitui os limites parciais, e sim os complementa: os limites parciais dão diagnóstico rápido e preciso; o total, a garantia de conclusão.

Como calcular o orçamento

Vá de cima para baixo, e não o contrário. Comece pela pergunta: qual é o tempo máximo de espera por um resultado aceitável para a tarefa de negócio? Para cenário interativo (o usuário esperando) — 3–10 segundos. Para scraping em segundo plano — 30–60 segundos. Para upload de arquivos grandes — calculado a partir do tamanho.

Depois esse orçamento é distribuído pelas fases conforme as distribuições medidas:

  • Estabelecimento do túnel via proxy (TCP mais CONNECT mais TLS): tipicamente 15–25 por cento do orçamento.
  • Escrita da requisição: 5–10 por cento para requisições comuns.
  • Espera pelo primeiro byte: 30–40 por cento.
  • Leitura do corpo: o restante.

Exemplo: orçamento de 30 segundos para scraping via proxy móvel. Connect (incluindo CONNECT) 6 segundos, TLS 4 segundos, write 3 segundos, read como intervalo de inatividade 10 segundos, prazo total 30 segundos. A soma dos limites parciais, 23 segundos, é menor que o orçamento — o que é normal, eles disparam separadamente. O prazo total pega os casos de entrega lenta que nenhum limite parcial pega.

Propagação do deadline pela cadeia

Em sistemas distribuídos, uma requisição raramente é isolada. Seu serviço recebeu uma tarefa com limite de 30 segundos, gastou 4 segundos se preparando, e então segue via proxy até o site de destino. Quanto tempo resta para a requisição HTTP? Não 30, e sim 26 segundos menos a folga para processar a resposta. Isso é a propagação do deadline: cada chamada seguinte recebe não um timeout fixo, mas o restante do orçamento.

No Go isso é implementado com um contexto com deadline, passado para a requisição. Em Python — via asyncio, com passagem explícita do tempo restante. Em Java — calculando um Duration antes de cada chamada. A regra é uma: o timeout da requisição HTTP é calculado dinamicamente, como o mínimo entre o limite estático e o restante do orçamento.

Sem isso aparece o problema clássico: a camada superior já desistiu de esperar e devolveu erro, enquanto a inferior ainda segura uma conexão via proxy por mais dez segundos e consome tráfego por um resultado que ninguém quer. Com tráfego pago de proxy móvel, isso é literalmente queimar dinheiro.

O pool de conexões e seus próprios timeouts

Mais dois limites que costumam ser esquecidos. Pool timeout — quanto esperar por uma conexão livre no pool, se todas estiverem ocupadas. Se não for definido, num pico de carga as requisições vão esperar indefinidamente, e por fora isso parece travamento do cliente. Coloque 1–3 segundos: se nesse tempo uma conexão não se liberou, o sistema está sobrecarregado e é melhor recusar logo.

Idle timeout de conexão no pool — por quanto tempo uma conexão keep-alive ociosa é mantida antes de ser fechada. Aqui o alinhamento com o proxy é crítico. Se o proxy fecha uma conexão ociosa em 60 segundos e o seu pool a mantém por 90 segundos, no 61º segundo você vai pegar do pool um socket morto, enviar uma requisição nele e receber connection reset — não um timeout, mas uma queda. Muitas bibliotecas repetem a requisição de forma transparente nessa situação, mas só para métodos idempotentes. Regra: o idle timeout do cliente deve ser estritamente menor que o idle timeout do proxy, com folga de ao menos 10–20 por cento.

Framework "orçamento de cima para baixo"

  1. Fixe a restrição de negócio para o tempo de espera pelo resultado.
  2. Subtraia o tempo de processamento próprio e a folga para retry, se houver.
  3. O restante obtido é o prazo total da requisição HTTP.
  4. Distribua-o pelas fases conforme o p99 medido de cada fase via seu proxy.
  5. Verifique que cada limite parcial é menor que o limite correspondente do lado do proxy.
  6. Defina o pool timeout e o idle timeout do pool, alinhados com o proxy.
  7. Implemente a passagem do restante do orçamento para chamadas aninhadas.
  8. Registre qual limite exatamente disparou e o tempo gasto em cada fase.

Método 5: observabilidade dos timeouts e ajuste adaptativo

Sem medição não há configuração

Todos os métodos anteriores esbarram numa coisa: você precisa conhecer as distribuições reais de tempo por fase via seu proxy. A única forma de saber é medir continuamente. Clientes modernos oferecem hooks de tracing: momento do início do DNS, estabelecimento do TCP, recebimento da resposta ao CONNECT, conclusão do TLS, envio da requisição, primeiro byte, último byte. Junte esses eventos em métricas separadas por proxy, host de destino e tipo de erro.

Quais métricas coletar

  • Histogramas de duração de cada fase, separados por endpoint de proxy e operadora.
  • Proporção de disparos de cada tipo de timeout sobre o total de requisições.
  • Proporção de timeouts antes do primeiro byte versus dentro do corpo.
  • Proporção de quedas de conexão sem timeout (sinal de limites de idle desalinhados).
  • Tempo médio gasto em requisições que terminaram em timeout — é seu prejuízo direto em tráfego e recursos.

Timeouts adaptativos

Tendência dos últimos anos que, em 2026, virou padrão em sistemas maduros — limites adaptativos. Em vez de um número estático, o cliente mantém uma janela deslizante de observações por par proxy-destino e define o timeout como o p99 da janela com um coeficiente de folga, limitado por cima e por baixo por valores razoáveis. Quando o canal piora, o limite sobe e os falsos positivos diminuem. Quando o canal melhora, o limite desce e o sistema reage mais rápido a problemas reais.

A implementação é simples: buffer circular com 200–500 medições recentes por chave, recálculo do quantil a cada poucos segundos, limites do tipo "nunca menor que 3 nem maior que 20 segundos para read". Importante se proteger da degradação: se todas as requisições começarem a dar timeout, a janela se enche de valores no nível do limite, e o limite só vai crescer. Por isso só entram na janela requisições bem-sucedidas, e o crescimento do limite é limitado pelo teto superior.

Requisições hedge

Para leitura via pool de vários proxies existe uma técnica que reduz o efeito das caudas lentas sem aumentar os timeouts: se a requisição não terminou em p99 do tempo, enviar uma duplicata por outro proxy e ficar com a primeira resposta que chegar. Isso aumenta o tráfego em alguns por cento, mas reduz radicalmente o p99 de latência. Serve apenas para requisições idempotentes e exige cancelar com cuidado a duplicata perdedora, para não gastar tráfego à toa.

Erros comuns: o que não fazer

Um único número para tudo

O erro mais comum. Um timeout único de 30 segundos significa que você vai levar meio minuto para detectar um proxy morto, e nunca vai detectar uma resposta lenta no meio do corpo. Separe as fases.

Ausência de timeouts por padrão

Várias bibliotecas populares não têm timeouts de fábrica: a requisição pode ficar pendurada indefinidamente. No requests isso ainda é assim. Qualquer chamada sem timeout explícito via proxy é um worker potencialmente bloqueado para sempre.

Read timeout maior que o idle limite do proxy

Você não vai ver timeouts, vai ver quedas de conexão e vai procurar o problema no lugar errado. Descubra os limites do seu provedor de proxy e configure o cliente estritamente abaixo.

Retry cego depois de read timeout em POST

Caminho direto para pedidos duplicados, cobranças em dobro e mensagens repetidas. Depois de um read timeout numa requisição não idempotente, o resultado é desconhecido — é preciso investigar, não adivinhar.

Ignorar a fase CONNECT

Achar que o connect timeout cobre o estabelecimento do túnel sem verificar isso na documentação da biblioteca específica. Em alguns clientes a fase CONNECT fica pendurada até o prazo total e, se ele não existe, indefinidamente.

Ajustar pelo máximo

Viu uma requisição de 45 segundos — colocou o limite em 60. Agora cada problema real custa um minuto de espera sua. Guie-se pelo p99 com folga, e deixe os outliers para o mecanismo de retry ou hedge.

Timeout sem cancelar o trabalho subjacente

A camada superior lançou exceção pelo seu limite, mas a requisição HTTP continua viva numa task em segundo plano. Erro especialmente comum em código assíncrono: o wrapper com timeout terminou, e a corrotina não foi cancelada. Garanta que o disparo do timeout resulte no fechamento real do socket.

Limites iguais para proxies de data center e móveis

A diferença de latência e jitter entre eles é de ordens de grandeza. Um perfil que funciona em proxy de servidor, em móvel gera uma avalanche de falsos timeouts. Mantenha perfis de configuração separados.

Ausência de pool timeout

Num pico de carga, as requisições esperam indefinidamente por uma conexão livre. Por fora, parece travamento do cliente inteiro com tráfego de rede zero.

Ferramentas e recursos

Diagnóstico pela linha de comando

curl continua sendo a ferramenta de referência para destrinchar as fases. As flags --connect-timeout, --max-time, --speed-limit, --speed-time cobrem todos os níveis, e o formato de saída -w com variáveis de tempo mostra quanto cada fase levou:

curl -x http://user:pass@proxy:port --connect-timeout 5 --max-time 30 -o /dev/null -s -w "dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}" https://example.com/

Atenção: via proxy, a variável time_connect mostra o tempo até o proxy, e time_appconnect mostra o tempo até a conclusão do TLS com o destino, ou seja, inclui o CONNECT. A diferença entre elas é o seu segundo hop.

Bibliotecas clientes e seus modelos de timeout

  • Python requests: tupla (connect, read). Não tem write nem timeout total; o total é implementado com wrapper externo ou cancelamento em nível de thread.
  • Python httpx: objeto Timeout com connect, read, write, pool. Não tem total, mas em modo assíncrono é fácil adicioná-lo com espera com limite e cancelamento.
  • Python aiohttp: ClientTimeout com os campos total, connect, sock_connect, sock_read. É o único entre os clientes Python populares com limite total embutido.
  • Go net/http: Dialer.Timeout, TLSHandshakeTimeout, ResponseHeaderTimeout, ExpectContinueTimeout, IdleConnTimeout no transport; Client.Timeout como total; contexto da requisição como deadline dinâmico.
  • Java HttpClient: connectTimeout no cliente, timeout na requisição (cobre até receber os cabeçalhos). A leitura do corpo é limitada no nível do BodyHandler ou por wrapper.
  • Node.js undici: connectTimeout, headersTimeout, bodyTimeout, keepAliveTimeout; total via AbortSignal.timeout.

Análise de tráfego

tcpdump e Wireshark permitem ver o que realmente aconteceu no fio: o SYN saiu, o SYN-ACK voltou, quem enviou FIN ou RST primeiro. É o único jeito confiável de responder à pergunta "quem derrubou a conexão — eu, o proxy ou o servidor". Para conteúdo HTTPS a visibilidade é limitada, mas as fases de conexão e túnel são plenamente visíveis.

Bancadas para reproduzir

Para testar o comportamento do cliente em travamentos, é útil ter um conjunto de dublês: servidor TCP que aceita conexão e fica em silêncio (teste de connect e CONNECT); servidor HTTP que responde cabeçalhos e depois fica em silêncio (teste de read antes do corpo); servidor que entrega um byte por segundo (teste de prazo total). Escrever esses dublês leva meia hora, e o tempo economizado em depuração em produção se mede em dias. Também existem ferramentas de emulação de rede que permitem adicionar latência, jitter e perdas na interface, para simular canal móvel em laboratório.

Observabilidade

Virou padrão coletar métricas e traces no formato OpenTelemetry, com instrumentação automática dos clientes HTTP. Histogramas por fase, atributos com identificador do proxy e tipo de limite disparado — conjunto mínimo sem o qual a configuração vira adivinhação.

Casos e resultados

Caso 1: scraping de marketplace via proxies móveis

A equipe coletava cards de produtos via pool de proxies móveis. Configuração inicial: timeout único de 15 segundos, sem prazo total, pool de conexões padrão. Sintomas: 11 por cento das requisições terminavam em erro, sendo dois terços timeouts e um terço quedas de conexão. Duração média de uma requisição malsucedida: 14 segundos — ou seja, a cada dez requisições, uma consumia tempo e tráfego em vão.

O diagnóstico por fases mostrou: p99 de estabelecimento de túnel — 4,8 segundos; p99 de TTFB — 6,2 segundos; pausa máxima entre chunks em respostas bem-sucedidas — 2,1 segundos; idle limite do túnel do provedor — 60 segundos, e o pool do cliente mantinha conexões por 120 segundos.

Mudanças: connect 7 segundos cobrindo CONNECT, read 9 segundos, write 5 segundos, prazo total 25 segundos, idle do pool 45 segundos, pool timeout 2 segundos. Separação, nas métricas, dos timeouts antes do primeiro byte e dentro do corpo.

Resultado depois de uma semana: a taxa geral de erros caiu para 3,4 por cento, as quedas de conexão praticamente sumiram, a duração média da requisição malsucedida caiu para 8 segundos. O consumo de tráfego por unidade de dado coletado diminuiu 19 por cento. Nada foi alterado na lógica de retry — apenas os timeouts.

Caso 2: integração com API de pagamento e duplicatas

O serviço enviava POSTs de criação de operações de pagamento via proxy corporativo. Read timeout de 10 segundos e retry automático em qualquer exceção. A cada poucos dias surgiam operações duplicadas. A análise revelou: a API de destino, em momentos de carga, respondia entre 11 e 14 segundos; o cliente desistia pelo read timeout, repetia a requisição, e as duas operações eram executadas com sucesso.

A solução teve três partes: read timeout elevado para 20 segundos com base no p99 medido de 15 segundos; o retry após read timeout em POST substituído por consulta de status da operação pelo identificador do cliente; e introdução de chave de idempotência no cabeçalho, suportada pela API. As duplicatas cessaram completamente. Conclusão separada da equipe: read timeout em requisição não idempotente não é um erro, é um estado de "resultado desconhecido" que exige um ramo próprio de tratamento.

Caso 3: upload de arquivos de mídia via canal móvel

O aplicativo subia vídeos de 50–200 megabytes via proxies móveis numa única requisição. Write timeout de 30 segundos, sem prazo total. Sintomas: cerca de 8 por cento dos uploads caíam, cada falha significava recomeçar do zero, e o excesso de tráfego diário chegava a dezenas de gigabytes.

Migração para upload em chunks de 4 megabytes com retomada, write timeout por chunk de 8 segundos, controle de velocidade mínima de 100 kilobytes por segundo por 10 segundos, prazo total por chunk de 60 segundos. A proporção de uploads totalmente fracassados caiu para 0,3 por cento, e o tráfego desperdiçado em repetições caiu 12 vezes, porque só o último chunk malsucedido era repetido.

Caso 4: travamento do CONNECT sem prazo total

Um coletor assíncrono em uma das bibliotecas Python congelava de vez em quando: workers vivos, rede em silêncio, fila parada. Depois de uma ou duas horas, o coletor era reiniciado à mão. A investigação mostrou: parte dos proxies do pool aceitava TCP, mas não respondia ao CONNECT. Na configuração usada, essa fase não era coberta por limite algum. A inclusão de um prazo total para a requisição inteira e de um limite explícito para o estabelecimento do túnel eliminou os travamentos. Além disso, foi adicionado um healthcheck de proxy verificando justamente a fase CONNECT, e não apenas a acessibilidade TCP.

FAQ: perguntas difíceis sobre timeouts via proxy

Qual a diferença entre timeout do cliente e resposta 504 do proxy?

O timeout do cliente é a sua decisão de parar de esperar; o proxy e o servidor só saberão dela pelo fechamento da conexão. A resposta 504 é a decisão do proxy: ele mesmo não esperou pelo servidor de destino e te informou isso com uma resposta HTTP completa. No primeiro caso, o socket é fechado com exceção; no segundo, você recebe uma resposta normal com código de erro. É preciso tratá-los de formas diferentes: o 504 significa que o proxy está vivo e o problema está mais abaixo na cadeia; o timeout do cliente não diz nada sobre onde exatamente travou.

Por que via proxy móvel são necessários timeouts mais longos que via proxy de data center?

Por causa do jitter. A latência média do canal celular não é tão alta, mas sua dispersão é enorme: trocas de setor, modos de economia de energia do modem, disputa por recurso de rádio. O timeout é configurado pela cauda da distribuição, e a cauda do canal móvel é várias vezes mais longa. Ao mesmo tempo, limites longos demais também fazem mal — atrasam a detecção de proxies realmente mortos. O equilíbrio se obtém medindo o p99 e aplicando folga de 30–50 por cento, e não dobrando todos os números.

Como saber qual timeout disparou, se a biblioteca lança uma única exceção genérica?

Três caminhos. O primeiro é pelo tempo: se a exceção veio em tempo igual ao connect timeout, e não ao read, você sabe a fase. O segundo é pelos hooks de tracing: se o evento "TLS concluído" ocorreu e o "primeiro byte" não, você travou no TTFB. O terceiro é pelo texto e tipo da exceção: muitas bibliotecas distinguem ConnectTimeout e ReadTimeout como classes separadas. Recomendamos sempre registrar quais fases foram concluídas antes da exceção — isso transforma um timeout misterioso em diagnóstico preciso.

Dá para repetir a requisição depois de disparar o write timeout?

Para GET sem corpo — sim, nada saiu. Para POST com corpo — só se você tiver certeza de que o servidor rejeita corpos incompletos. A maioria dos servidores faz isso: JSON incompleto ou multipart truncado geram erro de parsing. Mas APIs de streaming que começam a processar conforme recebem os dados podem aplicar mudanças parciais. Se tiver dúvida, verifique o estado antes de repetir.

Como alinhar os timeouts do cliente com os do provedor de proxy?

Peça ao provedor ou procure na documentação três valores: limite de conexão com o host de destino, idle limite do túnel e tempo máximo de vida da conexão. Seu limite para estabelecer o túnel deve ser maior ou igual ao do provedor (senão você desiste antes de o proxy conseguir), e seu read timeout e idle do pool devem ser estritamente menores que os idle limites do provedor. Se não houver documentação, meça empiricamente: abra a conexão, fique em silêncio por N segundos, tente enviar uma requisição e encontre o limiar a partir do qual vem a queda.

Preciso de um prazo total, se todos os limites parciais estão configurados?

Sim, obrigatoriamente. Limites parciais não restringem o tempo total: entrega lenta de corpo a um kilobyte por vez com intervalo menor que o read timeout pode durar indefinidamente. O prazo total é a única garantia de que o worker vai se liberar. Além disso, na propagação do orçamento pela cadeia de chamadas é o prazo total que é passado adiante, enquanto os limites parciais permanecem configuração local.

Como HTTP/2 e HTTP/3 afetam o modelo de timeouts via proxy?

O HTTP/2 multiplexa muitas requisições numa única conexão, então o read timeout em nível de socket deixa de ser o timeout de uma requisição: o socket recebe dados de outros fluxos, e a inatividade de uma requisição específica passa despercebida. São necessários limites em nível de fluxo — a maioria dos clientes HTTP/2 os oferece via deadline da requisição. O HTTP/3 sobre QUIC muda também a fase de conexão: o handshake é combinado com a criptografia, e o connect timeout cobre os dois. Via proxy CONNECT clássico, o HTTP/3 até o destino geralmente não passa — o túnel é orientado a TCP, e o cliente faz fallback para HTTP/2 ou HTTP/1.1. Extensões para tunelamento UDP via proxy estão evoluindo, mas em 2026 sua adoção nos clientes populares é limitada.

O que fazer se, depois do timeout, a conexão volta para o pool e a requisição seguinte falha?

Isso sinaliza que o cliente não fechou o socket corretamente ou que o pool não marcou a conexão como danificada. Uma conexão que sofreu read timeout não pode ser reaproveitada: pode haver bytes de uma resposta atrasada nela, que serão lidos como resposta da requisição seguinte. Garanta que o seu cliente, ao dar timeout, feche a conexão em vez de devolvê-la ao pool. Em clientes bem projetados, esse é o comportamento padrão, mas com wrappers próprios e trabalho de baixo nível com sockets o erro aparece com frequência.

Como configurar timeouts para proxy SOCKS5 em vez de proxy HTTP?

O princípio é o mesmo, mudam as fases: no lugar do CONNECT há a saudação, a autenticação e o comando de conexão, ou seja, duas ou três idas e voltas até o proxy mais o tempo de conexão do proxy com o destino. Na maioria dos clientes, o handshake SOCKS inteiro cai sob o connect timeout. Garanta que o valor contemple não só o TCP até o proxy, mas também o tempo de estabelecimento da conexão do proxy com o destino via canal móvel — os mesmos 3–10 segundos.

Conclusão: timeouts como disciplina de engenharia

Vamos recapitular. Uma requisição HTTP via proxy não é uma operação única, mas uma cadeia de sete ou oito fases de espera, cada uma com sua natureza de atraso e suas consequências em caso de queda. Connect e TLS são seguros: nada chegou ao servidor e dá para tentar de novo. O write timeout deixa o servidor com dados incompletos. O read timeout é o mais traiçoeiro: a requisição foi entregue e possivelmente executada, e você não sabe disso. O prazo total não substitui os limites parciais, e sim protege contra a entrega lenta que eles não pegam.

Via proxies móveis tudo isso se intensifica: o segundo hop passa por um canal de alto jitter, e limites ajustados em proxies de servidor geram uma avalanche de falsos positivos. A única forma de configurá-los corretamente é medir as distribuições por fase através do seu proxy específico e definir limites pelo p99 com folga, alinhando-os aos limites do próprio proxy.

Seus próximos passos:

  1. Encontre no seu código cada chamada HTTP via proxy e verifique se ela tem timeouts explícitos para todas as fases e um prazo total.
  2. Descubra se o seu cliente cobre a fase CONNECT e como ele interpreta o read timeout — como inatividade ou como tempo total.
  3. Descubra os idle limites e os limites de conexão do seu provedor de proxy e alinhe a configuração do cliente a eles.
  4. Ative o tracing de fases e colete distribuições por uma semana.
  5. Recalcule os limites pelo p99 e separe perfis para proxies de data center e móveis.
  6. Separe o tratamento de timeouts para requisições idempotentes e não idempotentes.
  7. Adicione às métricas o tipo de limite disparado e a fase em que disparou.

Timeouts não são um parâmetro que se define uma vez e se esquece. São parte do contrato do seu sistema com o mundo exterior e, como todo contrato, exigem medição, revisão e alinhamento entre as partes. Faça isso uma vez, de forma sistemática — e você vai se surpreender com quanto mais silenciosos ficam seus logs e quanto mais barato fica o seu tráfego.