Diagnóstico de erros de proxy: 407, 502, 504 e tunnel connection failed — guia passo a passo

Os erros de proxy assustam pela sua imprevisibilidade. O request acabou de funcionar, e agora você vê um misterioso 407, 502 ou uma mensagem tunnel connection failed. A boa notícia: por trás de cada erro desses existe uma causa clara e lógica. Este guia vai te ensinar a ler essas mensagens como um livro aberto.

Introdução: por que você precisa deste guia e o que vai aprender

Trabalhar com proxy é como uma ligação telefônica através de um intérprete. Seu cliente fala com o proxy, o proxy fala com o site de destino, e a resposta volta pelo mesmo caminho. Quando algo quebra, é importante entender em qual ponto exato da cadeia surgiu o problema. É exatamente a isso que este guia se dedica.

O que você vai aprender no final:

• Habilidade de diferenciar instantaneamente um erro de proxy de um erro do site de destino.
• Entendimento do que significam os códigos 407, 502, 504, 403 e a mensagem tunnel connection failed.
• Capacidade de ler a saída do comando curl -v linha por linha, separando claramente os trechos cliente-proxy-servidor.
• Exemplos prontos de diagnóstico em curl, Python requests e Node.js com mensagens de erro reais.
• Uma tabela de diagnóstico rápido sintoma-causa-verificação, que você pode imprimir e ter sempre à mão.

Para quem é este guia. Ele foi escrito para quem está começando a trabalhar com proxy, mas também contém detalhes avançados para desenvolvedores experientes e especialistas em automação. Se você configura scrapers, trabalha com multcontas ou simplesmente quer entender por que seu script parou de receber dados de repente, este material é para você.

O que você precisa saber antes. Basta um entendimento básico do que é URL, porta e requisição HTTP. Não é necessário conhecimento profundo de redes. Vamos explicar todos os termos em linguagem simples ao longo do texto.

Quanto tempo vai levar. A primeira leitura leva cerca de 30-40 minutos. Praticar os exemplos no seu próprio projeto vai levar mais 20-30 minutos. Depois disso, diagnosticar um erro típico vai levar de um a dois minutos.

Uma observação importante sobre o tema. Neste guia, abordamos apenas os erros da própria camada de proxy. O código 429 (excesso de requisições) e as estratégias de retry não são tratados aqui, porque isso é um tema grande e separado, com sua própria lógica e abordagens. Para 429, é necessário um material específico sobre retries e limites. Aqui focamos estritamente no diagnóstico de falhas de conexão de proxy.

Preparação inicial: ferramentas e acessos

Antes de começar o diagnóstico, vamos montar um conjunto de ferramentas. Todas são gratuitas e funcionam em qualquer sistema operacional.

Ferramentas necessárias

1. Instale o curl. Na maioria dos sistemas Linux e macOS, ele já vem instalado. Verifique com o comando curl --version. Se aparecer o número da versão, está tudo pronto.
2. No Windows, o curl faz parte do sistema a partir das versões modernas. Abra o PowerShell e digite o mesmo comando de verificação.
3. Instale o Python versão 3.10 ou superior, se pretende usar os exemplos com requests. Verifique com o comando python --version.
4. Instale a biblioteca requests com o comando pip install requests no terminal.
5. Instale o Node.js versão 20 ou superior para os exemplos em JavaScript. Verifique com o comando node --version.

O que você precisa preparar

• Os dados do seu proxy: endereço do host, porta, login e senha, se forem necessários.
• Um endereço de destino de teste para fazer as requisições. Para verificações, é prático usar um site simples que retorna informações sobre a requisição.
• Um editor de texto para salvar logs e anotações de diagnóstico.

Dica: Crie um arquivo de texto separado chamado diagnostic-notes. Anote nele cada comando e seu resultado. Isso vai te salvar quando, daqui a meia hora, você esquecer o que já testou.

⚠️ Atenção: Nunca salve login e senha do proxy em chats públicos, repositórios públicos ou prints. O vazamento desses dados dá a estranhos acesso ao seu tráfego. Guarde-os em um gerenciador de senhas seguro.

✅ Verificação: Nesta etapa, você deve conseguir executar com sucesso os três comandos de verificação de versão: curl, python e node. Se pelo menos um não funcionar, volte à instalação da ferramenta necessária.

Conceitos básicos em linguagem simples

Para que o diagnóstico seja consciente, vamos revisar alguns termos-chave. Não pule esta seção, mesmo que os termos pareçam familiares.

O que é um proxy de verdade

Proxy é um intermediário entre o seu programa e o site de destino. Sua requisição primeiro chega ao proxy, e o proxy a repassa adiante. A resposta volta pelo mesmo caminho. Por causa dessa intermediação, qualquer erro pode surgir em três lugares: no seu cliente, no próprio proxy ou no site de destino.

A divisão principal: cliente, proxy, servidor

Memorize os três elos da cadeia. O primeiro elo é o seu cliente, ou seja, o programa que envia a requisição. O segundo elo é o proxy, o intermediário. O terceiro elo é o servidor de destino, o site onde você quer chegar. Todo o diagnóstico se resume à pergunta: em qual dos três elos ocorreu a falha?

Códigos HTTP em poucas palavras

Sites e proxies respondem com códigos numéricos. Códigos que começam com 4 (por exemplo, 407, 403) geralmente indicam um problema do lado da requisição ou do acesso. Códigos que começam com 5 (502, 504) indicam um problema do lado do servidor ou do intermediário. Mas há uma sutileza traiçoeira aqui: o código 502 pode ser enviado tanto pelo site de destino quanto pelo próprio proxy. Aprender a diferenciá-los é um dos principais objetivos deste guia.

Diferença entre HTTP e HTTPS através do proxy

Quando você acessa um site comum via HTTP, o proxy vê toda a requisição por inteiro. Quando você acessa um site seguro via HTTPS, o proxy não consegue ler o conteúdo. Em vez disso, o cliente pede ao proxy para criar um túnel seguro com um comando especial chamado CONNECT. É por isso que o erro tunnel connection failed aparece apenas em HTTPS. Vamos analisar isso em detalhes separadamente.

Dica: Mantenha na cabeça uma imagem simples. O cliente bate na porta do proxy. O proxy decide se deixa entrar. Depois, o proxy bate na porta do site. O site decide se responde. O erro surge na batida que não deu certo.

Passo 1: Como diferenciar um erro de proxy de um erro do site de destino

Objetivo da etapa: aprender a entender em poucos segundos quem é o culpado — o proxy ou o site. Essa é a habilidade fundamental com que começa qualquer diagnóstico.

Princípio principal de separação

A pergunta-chave é: sua requisição chegou ao site de destino ou ficou presa no proxy? Se a requisição ficou presa no proxy, a culpa é da camada de proxy. Se a requisição chegou ao site e o site respondeu, o problema está do lado do site.

1. Observe o código do erro e o texto da mensagem.
2. Determine quem enviou essa resposta: o proxy ou o servidor. O cabeçalho da resposta e o conteúdo vão te contar isso.
3. Se o texto do erro menciona diretamente a palavra proxy, tunnel ou o nome do programa de proxy, quase com certeza a culpa é da camada de proxy.
4. Se a resposta contém uma página HTML familiar do site de destino, com seu logo e layout, significa que a requisição chegou ao site.

Três sinais rápidos de erro especificamente de proxy

• Código 407. Esse código só existe em proxies. O site de destino nunca o envia. Viu 407 — significa que você está definitivamente na camada de proxy.
• Texto tunnel connection failed ou Received HTTP code do proxy. Essas formulações são geradas justamente pelo intermediário.
• Recusa instantânea de conexão. Se a requisição falha praticamente na hora, antes mesmo de poder chegar ao site, provavelmente o problema está entre o cliente e o proxy.

Dica: Faça um teste de controle. Faça exatamente a mesma requisição diretamente, sem proxy. Se diretamente funciona e via proxy não, o problema está na camada de proxy ou na interação dela com o site. Isso elimina metade das hipóteses em um minuto.

Exemplo em curl para verificação rápida

Execute uma requisição através do proxy com a flag de saída detalhada. O comando é assim: curl -v -x http://login:senha@host:porta https://exemplo-site. A flag -v mostra todo o diálogo. A flag -x define o proxy. Observe as linhas que começam com setas e asteriscos. Vamos falar detalhadamente sobre elas em um passo separado sobre leitura de logs.

⚠️ Atenção: Nunca tire conclusões com base em uma única requisição a um site instável. Repita a requisição duas ou três vezes. Uma falha isolada de rede pode parecer um erro de proxy, mesmo que o proxy não tenha nada a ver com isso.

✅ Verificação: Você deve ser capaz de responder, para qualquer mensagem de erro, à pergunta: isso foi enviado pelo proxy ou pelo site? Se conseguir, siga adiante. Se ainda tiver dúvidas, volte aos três sinais rápidos acima.

Passo 2: Erro 407 Proxy Authentication Required

Objetivo da etapa: aprender a corrigir o erro de autorização de proxy mais comum e entender como ele se diferencia do código parecido 401.

O que significa 407 e como ele difere de 401

O código 407 diz literalmente o seguinte: o proxy exige que você se identifique com login e senha, mas você não fez isso ou fez errado. A diferença principal em relação ao 401: o código 401 é enviado pelo site de destino, quando é ele quem exige autorização. Já o código 407 é enviado justamente pelo proxy. Se você vê 407, significa que nem chegou ao site — você foi barrado pelo intermediário na entrada.

Onde exatamente o login e a senha se perdem

Na maioria das vezes, os dados se perdem em três lugares.

1. Login e senha não foram enviados no comando. O cliente bateu na porta do proxy de forma anônima, e o proxy o recusou.
2. Os dados foram enviados, mas com um erro de digitação. Um espaço a mais ou um layout de teclado errado — e a autorização não passa.
3. Os dados foram enviados corretamente, mas a senha contém caracteres especiais que quebram a estrutura da string de conexão. Essa é a causa mais traiçoeira.

Caracteres especiais na senha e codificação URL

A string de conexão ao proxy é assim: login dois-pontos senha arroba host dois-pontos porta. O problema é que os dois-pontos, a arroba, a barra e outros caracteres têm significado especial dentro dessa string. Se sua senha contém, por exemplo, uma arroba ou dois-pontos, o programa vai entendê-la incorretamente e quebrar a string no lugar errado.

A solução se chama codificação URL. Os caracteres especiais são substituídos por um código composto pelo sinal de porcentagem e dois dígitos ou letras. Por exemplo, a arroba vira porcentagem quarenta, os dois-pontos viram porcentagem três A, a barra vira porcentagem dois F, o espaço vira porcentagem vinte.

1. Encontre todos os caracteres especiais na sua senha.
2. Substitua cada um pelo seu código URL.
3. Monte a string de conexão novamente com a senha codificada.
4. Repita a requisição.

Dica: Não codifique a senha manualmente se ela for complexa. No Python, existe uma função de codificação do módulo urllib.parse chamada quote. Passe a senha para ela, e ela retorna uma versão segura. Isso elimina erros de digitação manual.

Exemplo em curl

Um texto de erro real com autorização incorreta é assim: curl (56) Received HTTP code 407 from proxy after CONNECT. Ou, em site HTTP: HTTP 407 Proxy Authentication Required. O comando correto com autorização: curl -v --proxy-user login:senha -x http://host:porta https://exemplo-site. Usar a flag --proxy-user costuma ser mais confiável do que inserir os dados diretamente no endereço, porque o curl processa os caracteres corretamente.

Exemplo em Python requests

No requests, o proxy é definido através de um dicionário. As chaves são http e https, os valores são as strings de conexão. Se a senha contiver caracteres especiais, envolva-a na função quote. Um erro típico na resposta do objeto: response.status_code retorna 407, e no texto há menção a Proxy Authentication Required. Verifique justamente o status code, não apenas o texto.

Exemplo em Node.js

No Node, ao usar clientes de proxy populares, o proxy é definido através de um agente especial. O erro real aparece como um objeto com o campo statusCode igual a 407 ou como uma promise rejeitada com mensagem de erro de autorização de túnel. Certifique-se de enviar o cabeçalho de autorização do proxy, e não o cabeçalho de autorização do site — são coisas diferentes.

⚠️ Atenção: O cabeçalho de autorização do proxy e o cabeçalho de autorização do site são dois cabeçalhos diferentes. Um se chama Proxy-Authorization, o outro Authorization. Se você trocar, vai receber 407 do proxy ou 401 do site. Verifique qual cabeçalho sua biblioteca está enviando.

✅ Verificação: Depois de corrigir a autorização, o código de resposta deve mudar de 407 para qualquer outro. Mesmo que o site responda com um erro dele, isso já é progresso: você passou pelo proxy e chegou ao site.

Passo 3: Erro 502 do proxy

Objetivo da etapa: aprender a entender quando o 502 significa um problema do site de destino e quando significa uma falha do próprio canal de proxy.

O que significa 502

O código 502 se chama Bad Gateway, ou seja, gateway ruim. Ele diz que o intermediário tentou se comunicar com o próximo elo, mas recebeu uma resposta confusa ou interrompida. O problema é que o 502 pode chegar em duas situações completamente diferentes, e elas parecem iguais por fora.

Quando a culpa é do host de destino

Primeira situação: o proxy se conectou com sucesso ao site de destino, mas o site retornou lixo, interrompeu a conexão ou ele mesmo não conseguiu obter resposta do seu backend. Nesse caso, o proxy repassou honestamente o 502 para você como constatação: cheguei ao site, mas o site respondeu mal.

1. Faça a mesma requisição diretamente, sem proxy.
2. Se diretamente o site também responde 502 ou trava, a culpa é do site, não do proxy.
3. Nesse caso, trocar de proxy é inútil. O problema está do lado do destino.

Quando a culpa é do próprio canal

Segunda situação: o próprio proxy está instável, seu canal upstream caiu, ou o proxy nem conseguiu estabelecer a conexão direito com o site. Então o 502 é um sinal de intermediário doente.

1. Faça uma requisição através do mesmo proxy a um site comprovadamente estável.
2. Se até o site estável retorna 502, o problema está no canal de proxy.
3. Tente outro proxy ou outro nó, se você tiver algum.

Dica: O método de verificação cruzada funciona infalivelmente. Mude uma variável de cada vez. Primeiro fixe o proxy e mude o site. Depois fixe o site e mude o proxy. A intersecção dos resultados vai mostrar o culpado.

Textos de erro reais

No curl, você vai ver uma resposta HTTP com código 502 e, muitas vezes, uma página HTML com a inscrição Bad Gateway. Às vezes, nos cabeçalhos da resposta, dá para ver um indício de qual servidor enviou a resposta. No Python requests, é response.status_code igual a 502. No Node, é o campo statusCode igual a 502. Preste atenção ao corpo da resposta: uma página bem formatada do site de destino indica que a requisição chegou ao site, enquanto uma página técnica enxuta geralmente vem do proxy.

⚠️ Atenção: Não se apresse em culpar o proxy no primeiro 502. Sites de destino retornam 502 com muita frequência, especialmente sob carga. Sempre faça uma requisição de controle diretamente, antes de mudar as configurações do proxy.

✅ Verificação: Você deve ser capaz de, com base nos resultados de duas requisições cruzadas, dizer com segurança: esse 502 é do site ou do proxy. Se ainda não conseguir, repita as duas requisições de controle e compare os resultados.

Passo 4: Erro 504 e timeouts

Objetivo da etapa: aprender a diferenciar dois tipos fundamentalmente distintos de timeout e configurá-los corretamente no cliente.

O que significa 504

O código 504 se chama Gateway Timeout, ou seja, o gateway não esperou a resposta. Ele diz que o intermediário esperou demais por uma resposta do próximo elo e desistiu. Mas para entender onde exatamente o tempo travou, é preciso dividir dois tipos de timeout.

Connect timeout versus read timeout

Existem dois momentos de espera completamente diferentes.

• Connect timeout — é o tempo para estabelecer a conexão em si. O cliente tenta ligar para o proxy, ou o proxy para o site. Se a conexão não é estabelecida dentro do tempo previsto, o connect timeout dispara. Geralmente, isso é sinal de que o endereço está indisponível ou a porta está fechada.
• Read timeout — é o tempo de espera pela resposta depois que a conexão já foi estabelecida. A conexão existe, a requisição foi enviada, mas os dados não chegam. Geralmente, isso é sinal de que o site está demorando para pensar ou travou no processamento.

Como separá-los no cliente

O diagnóstico correto começa com a configuração separada desses dois timeouts. Assim, você vai entender imediatamente em que etapa o tempo travou.

1. No curl, use a flag --connect-timeout para limitar o tempo de estabelecimento de conexão. Separadamente, a flag --max-time limita o tempo total de toda a operação.
2. No Python requests, o parâmetro timeout pode ser passado como uma tupla de dois números. O primeiro número é o connect timeout, o segundo é o read timeout. Por exemplo, timeout de cinco e trinta segundos.
3. No Node, na maioria dos clientes, há configurações separadas para o tempo de conexão e para o tempo de espera pela resposta. Defina valores diferentes para ver qual disparou.

Como ler o resultado

Se o connect timeout disparou, significa que você nem estabeleceu a conexão. Verifique a disponibilidade do proxy e a correção da porta. Se o read timeout disparou, significa que a conexão existia, mas a resposta não chegou a tempo. Verifique se o site está sobrecarregado e se a requisição que você está fazendo não é pesada demais.

Dica: Defina o connect timeout como pequeno, em torno de cinco segundos. O estabelecimento de conexão ou acontece rápido, ou não acontece de jeito nenhum. Já o read timeout deve ter uma folga, porque algumas páginas realmente demoram mais para preparar a resposta.

⚠️ Atenção: Um read timeout pequeno demais gera falsos erros. Você vai cortar respostas normais, mas lentas, e pensar que o proxy está quebrado. Sempre verifique se você mesmo não definiu um limite rígido demais.

Textos de erro reais

No curl, o connect timeout aparece como a mensagem Connection timed out após o stderr. No Python requests, é a exceção ConnectTimeout para a conexão e ReadTimeout para a resposta. O próprio nome da exceção já diz qual etapa falhou. No Node, você vai ver um erro com código ETIMEDOUT ou uma mensagem separada sobre estouro do tempo de resposta.

✅ Verificação: Depois de configurar os timeouts separados, você deve receber no erro uma indicação clara: é timeout de conexão ou timeout de leitura. Se você vê apenas a palavra genérica timeout sem especificação, significa que os timeouts ainda não estão separados.

Passo 5: Erro tunnel connection failed e o método CONNECT

Objetivo da etapa: entender por que esse erro só aparece em sites seguros e como diagnosticá-lo.

Por que o erro só aparece em HTTPS

Quando você acessa um site HTTP comum, o proxy simplesmente repassa sua requisição. Mas quando você acessa um site HTTPS, o conteúdo está criptografado e o proxy não consegue lê-lo. Por isso, o cliente primeiro envia ao proxy um comando especial CONNECT com o endereço do site. Esse comando significa um pedido: por favor, construa para mim um túnel seguro até esse endereço, eu vou me comunicar com o site diretamente através de você.

Se, por algum motivo, o proxy não conseguiu construir o túnel, ele retorna o erro tunnel connection failed. No HTTP comum não existe esse comando, portanto esse erro também não existe em HTTP. Esse é o seu principal sinal de identificação.

Principais causas de falha no túnel

• O proxy não conseguiu se conectar ao endereço de destino. Talvez o site esteja indisponível ou a porta esteja fechada.
• O proxy proíbe o método CONNECT para esse endereço ou porta. Alguns proxies permitem apenas determinadas portas.
• A autorização não passou. Nesse caso, você costuma ver uma combinação: primeiro a tentativa de CONNECT, depois o código 407.
• O proxy está sobrecarregado ou seu canal upstream caiu no momento de construir o túnel.

Como diagnosticar

1. Execute curl -v para um endereço HTTPS e encontre na saída a linha com CONNECT. Ela mostra o momento do pedido de túnel.
2. Veja qual resposta veio ao CONNECT. Uma resposta com código 200 significa que o túnel foi construído. Qualquer outro código significa falha.
3. Se você vê 407 por perto, o problema está na autorização, não no túnel em si. Volte ao passo sobre 407.
4. Se você vê recusa de conexão, o proxy não conseguiu chegar ao site.

Dica: Verifique se você está acessando exatamente a porta permitida. As portas clássicas para conexões seguras costumam ser permitidas, mas muitos proxies bloqueiam portas não padronizadas. Trocar a porta por uma padrão costuma resolver o problema instantaneamente.

Textos de erro reais

No curl, é uma mensagem do tipo curl (56) Received HTTP code do proxy after CONNECT ou diretamente tunnel connection failed. No Python requests, é a exceção ProxyError com uma mensagem aninhada sobre túnel malsucedido. No Node, é um erro com texto dizendo que a conexão de túnel não pôde ser estabelecida, muitas vezes com indicação do código de status do proxy.

⚠️ Atenção: Não confunda falha de túnel com erro de certificado. Se o túnel foi construído, mas depois reclama do certificado seguro do site — isso já é outro problema, não relacionado à camada de proxy. Veja em que etapa exatamente o erro surgiu: antes da resposta ao CONNECT ou depois.

✅ Verificação: Você deve encontrar na saída do curl a linha com a resposta ao CONNECT e entender pelo seu código se o túnel foi construído ou não. Resposta 200 — o túnel existe. Outro código — procure a causa da falha.

Passo 6: Erro 403 do proxy

Objetivo da etapa: aprender a reconhecer quando o 403 é enviado pelo proxy por causa de limites, geografia ou porta proibida.

O que significa 403 no contexto de proxy

O código 403 se chama Forbidden, ou seja, proibido. Normalmente, esse código é enviado pelo site de destino quando ele bloqueia o acesso. Mas o proxy também pode enviar 403 quando ele mesmo decide não deixar passar sua requisição. A tarefa é entender quem exatamente impôs a proibição.

Três causas de 403 do proxy

• Limites. O proxy pode limitar a quantidade de requisições, o volume de tráfego ou o número de conexões simultâneas. Ao ultrapassar, ele retorna 403 como recusa de atendimento.
• Restrição geográfica. Alguns proxies permitem acesso apenas a determinadas regiões ou, ao contrário, proíbem determinadas direções. Uma requisição a uma direção fechada recebe 403.
• Porta proibida. O proxy pode permitir apenas portas padrão. Uma requisição a uma porta não padronizada resulta em recusa.

Como diferenciar 403 do proxy de 403 do site

1. Observe o corpo da resposta. Uma página bem formatada do site de destino, com seu design, significa que a proibição veio do site.
2. Uma página técnica enxuta ou menção ao proxy no texto significa que a proibição veio do intermediário.
3. Faça a mesma requisição diretamente. Se diretamente o site retorna 403, e via proxy também, a culpa é do site.
4. Se diretamente o site abre, mas via proxy retorna 403, procure a causa nos limites ou restrições do proxy.

Dica: Verifique a documentação ou o painel de controle do seu proxy quanto a limites. Muitas vezes, no painel, dá para ver se o tráfego acabou ou se o limite de requisições foi atingido. Essa é a maneira mais rápida de confirmar a causa.

⚠️ Atenção: Não tente burlar os limites do proxy com truques. Se você bateu no limite do seu plano, a solução correta é ampliar o plano ou otimizar a quantidade de requisições. Burlar restrições técnicas do serviço viola os termos de uso.

Textos de erro reais

No curl, é uma resposta HTTP 403 Forbidden com um corpo que vai indicar a origem. No Python requests, é response.status_code igual a 403. No Node, é statusCode igual a 403. Sempre analise o corpo da resposta junto com o código, porque é justamente o corpo que revela o verdadeiro autor da proibição.

✅ Verificação: Você deve, pelo corpo da resposta e pelo resultado da requisição direta, determinar quem enviou o 403. Se foi o proxy — verifique limites, geografia e porta. Se foi o site — a causa não está na camada de proxy.

Passo 7: Queda de conexão sem resposta — connection reset e EOF

Objetivo da etapa: aprender a diagnosticar os casos mais misteriosos, quando não há resposta nenhuma e a conexão simplesmente cai.

O que são esses erros

Às vezes, você não recebe nenhum código HTTP. Em vez disso, a conexão cai de repente. Existem dois sinais típicos.

• Connection reset. Ao pé da letra — conexão reiniciada. Uma das partes fechou o canal abruptamente, sem terminar a troca. Como se o interlocutor tivesse desligado o telefone no meio da frase.
• EOF, unexpected end of file. Ao pé da letra — fim inesperado dos dados. O cliente esperava a continuação da resposta, mas o fluxo de dados terminou de repente.

O que observar em primeiro lugar

1. Determine o momento da queda. Ela ocorreu antes da resposta ao CONNECT, durante o envio da requisição ou durante o recebimento da resposta? A saída do curl -v mostra a última linha bem-sucedida antes da queda.
2. Se a queda ocorreu logo no início, ao conectar ao proxy, provavelmente o problema está no próprio proxy ou no caminho de rede até ele.
3. Se a queda ocorreu depois de estabelecer o túnel, durante a comunicação com o site, provavelmente o problema está do lado do site ou de um canal instável.
4. Repita a requisição várias vezes. Uma queda que se repete de forma consistente indica uma causa sistêmica. Uma queda aleatória indica instabilidade temporária de rede.

Causas frequentes

• O proxy está sobrecarregado e fecha à força as conexões excedentes.
• O canal upstream do proxy está instável e cai.
• O site de destino fecha a conexão por causa das próprias restrições.
• Problemas de rede entre os elos da cadeia.

Dica: Em caso de quedas aleatórias, mantenha estatísticas. Faça, por exemplo, vinte requisições seguidas e conte quantas caíram. Se cai uma em cada vinte, é uma instabilidade tolerável. Se cai metade, há um problema sistêmico que precisa ser resolvido.

Textos de erro reais

No curl, é Connection reset by peer ou Empty reply from server. No Python requests, é a exceção ConnectionError com uma mensagem aninhada sobre reset de conexão. No Node, é um erro com código ECONNRESET. Essas mensagens não contêm código HTTP justamente porque a troca HTTP não foi concluída normalmente.

⚠️ Atenção: Uma queda sem resposta é fácil de confundir com um timeout. A diferença é que, no timeout, o cliente mesmo interrompe a espera, enquanto no reset, a outra parte fecha o canal ativamente. Observe o texto do erro: a palavra reset indica fechamento ativo, a palavra timeout indica expiração da espera.

✅ Verificação: Você deve, pela última linha da saída do curl, determinar em que etapa a conexão caiu. Isso já reduz o círculo de suspeitos a um ou dois elos.

Passo 8: Prática — lendo o curl -v linha por linha

Objetivo da etapa: aprender a enxergar na saída do curl a fronteira entre cliente, proxy e servidor. Essa é a coroa de todo o guia.

O que significam os símbolos no início das linhas

A saída do curl -v usa símbolos especiais no início de cada linha, e essa é a sua principal chave de entendimento.

• O asterisco no início da linha significa uma mensagem informativa do próprio curl. São comentários do cliente sobre o que ele está fazendo: estabelecendo conexão, construindo túnel, verificando certificado.
• A seta para a direita significa dados que o cliente envia ao proxy ou ao servidor. É a requisição de saída.
• A seta para a esquerda significa dados que o cliente recebe em resposta. É a resposta de entrada.

Onde passa a fronteira cliente-proxy-servidor

Vamos analisar um caminho típico até um site seguro através do proxy. Primeiro, o curl informa com asterisco que está se conectando ao proxy pelo endereço e porta indicados. Esse é o trecho cliente-proxy. Em seguida vem uma seta de saída com o comando CONNECT — o cliente pede ao proxy para construir o túnel. Depois, uma seta de entrada com a resposta ao CONNECT — é a resposta do proxy. Se o código for 200, o túnel foi construído, e a fronteira muda: daí em diante, toda a troca já é cliente-servidor através do túnel.

Análise de um log real

Vamos supor que você veja esta sequência. Uma linha com asterisco: conectando ao endereço e porta do proxy. Isso significa que o cliente encontrou o proxy. A próxima linha com asterisco: conexão com o proxy estabelecida. Ótimo, o primeiro trecho foi superado. Depois, uma seta de saída: CONNECT para o endereço do site de destino. O cliente pediu o túnel. Então, uma seta de entrada: resposta ao CONNECT com um código. Aqui está a bifurcação principal.

1. Se o código da resposta ao CONNECT for 200, o túnel foi construído. Continue lendo.
2. Se o código for 407, o proxy exige autorização. O problema está na camada de proxy, no trecho cliente-proxy. Vá ao passo sobre 407.
3. Se a linha diz tunnel connection failed, o proxy não conseguiu construir o túnel. A causa está entre o proxy e o site.

Suponhamos que o túnel foi construído. Depois vêm asteriscos sobre a verificação da conexão segura com o site. Esse já é o trecho cliente-servidor. Em seguida, uma seta de saída com a requisição real: a linha de requisição e os cabeçalhos. Repare: até esse momento, o site nem viu sua requisição, estava ocupado construindo o túnel. E, finalmente, a seta de entrada com o código de resposta do site. Aqui começa a zona de responsabilidade do site de destino.

Como aplicar isso no diagnóstico

1. Encontre a linha de estabelecimento de conexão com o proxy. Se ela não existe ou tem erro, o problema está entre o cliente e o proxy.
2. Encontre a resposta ao CONNECT. Pelo seu código, determine se a camada de proxy passou.
3. Encontre a seta de entrada com a resposta do site. Se ela existe, significa que você chegou ao site, e qualquer erro ali já é da zona do site.
4. A última linha antes da queda sempre indica em que trecho tudo quebrou.

Dica: Leia a saída de cima para baixo como uma crônica da viagem da requisição. Cada linha é um passo do caminho. Assim que você chegar à linha com erro ou queda, olhe para a linha bem-sucedida anterior. Ela vai indicar o último elo vivo.

⚠️ Atenção: A flag -v mostra os cabeçalhos, incluindo a linha de autorização do proxy. Se você compartilhar o log com alguém para pedir ajuda, certifique-se de apagar a linha com os dados de autorização. Caso contrário, você vai revelar seu login e senha.

✅ Verificação: Pegue qualquer log seu do curl -v e marque nele: onde está o trecho cliente-proxy, onde está a resposta ao CONNECT, onde começa a zona do site. Se você traça essas fronteiras com segurança, dominou a principal habilidade de diagnóstico.

Passo 9: Tabela de diagnóstico rápido sintoma-causa-verificação

Objetivo da etapa: ter em mãos um guia de referência pronto, ao qual você pode recorrer no momento de qualquer erro.

Como usar a tabela

Encontre seu sintoma na primeira coluna. Leia a causa provável. Execute a ação da terceira coluna em primeiro lugar — ela tem a maior probabilidade de confirmar ou refutar a causa.

Sintoma: código 407

Causa provável: dados de autorização do proxy não enviados ou incorretos, ou caracteres especiais na senha quebraram a string de conexão. O que verificar primeiro: a correção do login e da senha, além da codificação URL dos caracteres especiais na senha.

Sintoma: tunnel connection failed em HTTPS

Causa provável: o proxy não conseguiu construir o túnel até o site, possivelmente por porta proibida ou indisponibilidade do site. O que verificar primeiro: a resposta ao CONNECT na saída do curl -v e se a porta de destino é permitida.

Sintoma: código 502

Causa provável: resposta ruim do próximo elo, culpa do site ou de um canal de proxy instável. O que verificar primeiro: requisição cruzada — o mesmo site diretamente e o mesmo proxy a um site estável.

Sintoma: código 504

Causa provável: tempo de espera esgotado, é preciso entender — de conexão ou de resposta. O que verificar primeiro: connect timeout e read timeout separados, para ver qual etapa se prolongou.

Sintoma: código 403 através do proxy

Causa provável: limites do proxy, restrição geográfica ou porta proibida. O que verificar primeiro: o corpo da resposta quanto à origem da proibição e o painel de controle do proxy quanto a limites esgotados.

Sintoma: connection reset ou ECONNRESET

Causa provável: uma das partes fechou a conexão à força, muitas vezes um proxy sobrecarregado ou um canal instável. O que verificar primeiro: a etapa da queda pela última linha do curl -v e a repetibilidade do problema ao longo de uma série de requisições.

Sintoma: EOF, empty reply

Causa provável: o fluxo de dados foi interrompido antes do fim da resposta. O que verificar primeiro: em que trecho ocorreu a queda — antes ou depois da resposta ao CONNECT.

Sintoma: connect timeout

Causa provável: impossível estabelecer conexão, endereço indisponível ou porta fechada. O que verificar primeiro: a disponibilidade do endereço do proxy e a correção da porta.

Sintoma: read timeout

Causa provável: conexão existe, mas a resposta não chega, o site demora para processar ou travou. O que verificar primeiro: se o seu read timeout não é pequeno demais e se o site não está sobrecarregado.

Dica: Imprima esta tabela ou salve nas suas anotações. No momento de um erro real, sob pressão, é fácil esquecer a lógica. Um guia de referência pronto economiza nervos e tempo.

✅ Verificação: Passe pela tabela cada um dos seus erros recentes. Para qualquer um deles, você deve saber qual é a primeira ação de verificação.

Verificação do resultado: checklist do diagnosticador

Certifique-se de que você dominou todas as habilidades principais. Percorra o checklist.

• Você consegue responder em segundos quem enviou o erro — o proxy ou o site.
• Você entende a diferença entre 407 e 401 e sabe corrigir a autorização, incluindo caracteres especiais na senha.
• Você diferencia 502 do site e 502 do proxy através da verificação cruzada.
• Você separa connect timeout e read timeout e sabe o que cada um significa.
• Você entende por que tunnel connection failed só acontece em HTTPS e sabe ler a resposta ao CONNECT.
• Você reconhece as três causas de 403 do proxy: limites, geografia e porta.
• Você diagnostica quedas de conexão pela etapa em que ocorreram.
• Você lê a saída do curl -v linha por linha e traça as fronteiras cliente-proxy-servidor.

Como se testar

1. Pegue três logs reais com erros diferentes.
2. Para cada um, determine o elo culpado em um minuto.
3. Diga qual é a primeira ação de verificação pela tabela.
4. Se você conseguiu com os três, o diagnóstico está dominado.

✅ Verificação: O indicador de sucesso é você não entrar mais em pânico ao ver um erro de proxy, mas decompô-lo calmamente pelos elos da cadeia.

Erros típicos e soluções

Problema: troco de proxy imediatamente a qualquer erro

Causa: falta de hábito de verificação cruzada. Solução: sempre faça uma requisição de controle diretamente e a um site estável, antes de mudar as configurações. Metade dos erros acaba sendo do lado do site.

Problema: senha com arroba quebra a conexão

Causa: o caractere especial não está codificado e quebra a string. Solução: aplique codificação URL à senha ou use um parâmetro separado de autorização em vez de inserir no endereço.

Problema: confundo 407 e 401

Causa: não diferencio autorização de proxy e autorização de site. Solução: lembre-se — 407 é sempre do proxy, 401 é sempre do site. Verifique qual cabeçalho você envia: Proxy-Authorization ou Authorization.

Problema: timeout rígido demais corta requisições normais

Causa: read timeout definido pequeno demais. Solução: separe os timeouts de conexão e de leitura, dê ao read uma folga para páginas lentas.

Problema: tunnel connection failed em porta não padronizada

Causa: o proxy proíbe CONNECT para essa porta. Solução: use a porta padrão para conexões seguras ou confirme a lista de portas permitidas do proxy.

Problema: vejo 502 e acho que o proxy morreu

Causa: não verifiquei quem enviou o 502. Solução: verificação cruzada. Muitas vezes, o 502 vem de um site de destino sobrecarregado, e o proxy está funcionando.

Problema: revelei login e senha no log

Causa: compartilhei a saída do curl -v sem limpar. Solução: sempre apague a linha de autorização antes de enviar o log a alguém e, se possível, troque os dados comprometidos.

Problema: considero uma queda de conexão como timeout

Causa: não diferencio reset e timeout. Solução: observe o texto do erro. Reset é fechamento ativo pela outra parte, timeout é expiração da sua espera. São causas diferentes.

Recursos adicionais para avançados

Logging contínuo

Configure o salvamento de logs detalhados de todas as requisições de proxy no seu aplicativo. Assim, quando surgir um erro, você já terá um histórico e não precisará reproduzir o problema de novo. Registre o código de resposta, a etapa da queda e o tempo de execução.

Classificação automática de erros

No código, você pode criar uma função que, pelo tipo de exceção e pelo código de resposta, já classifica o erro no elo certo. Por exemplo, ConnectTimeout — trecho de conexão, ReadTimeout — trecho de resposta, ProxyError com túnel — camada de proxy. Isso acelera a reação em sistemas automatizados.

Coleta de estatísticas de estabilidade

Mantenha métricas: proporção de requisições bem-sucedidas, proporção de quedas, tempo médio de resposta. Uma piora brusca nas métricas vai indicar um problema antes que você o encontre manualmente.

Dica: Separe as métricas por elo. Conte separadamente os erros de estabelecimento de conexão e os erros na etapa de resposta. Assim, você verá imediatamente o que está degradando — o acesso ao proxy ou a comunicação com os sites.

⚠️ Atenção: Ao construir o processamento automático, não o transforme em repetições infinitas da mesma requisição. A lógica de retry é um tema grande e separado, com regras próprias, relacionado inclusive ao código 429. Há um material dedicado a isso, que vale a pena estudar separadamente.

FAQ: perguntas frequentes sobre diagnóstico

Como entender rapidamente que a culpa é do proxy, e não do meu código?

Faça a mesma requisição diretamente, sem proxy. Se diretamente funciona e via proxy não, o problema está na camada de proxy ou na interação dela com o site. Isso elimina metade das hipóteses em um minuto.

Por que recebo 407 mesmo tendo digitado a senha correta?

Provavelmente, há caracteres especiais na senha que quebram a string de conexão. Aplique codificação URL à senha ou passe os dados por um parâmetro separado de autorização, em vez de no endereço.

O código 502 sempre significa que o proxy está quebrado?

Não. O 502 também pode ser enviado pelo site de destino, se ele mesmo respondeu mal. Faça uma verificação cruzada: o mesmo site diretamente e o mesmo proxy a um site estável. A intersecção dos resultados vai mostrar o culpado.

Qual é a diferença entre connect timeout e read timeout?

Connect timeout é a espera pelo estabelecimento da conexão. Read timeout é a espera pela resposta depois que a conexão já foi estabelecida. Separe-os no cliente e você verá imediatamente qual etapa se prolongou.

Por que tunnel connection failed só acontece em HTTPS?

Porque, para sites seguros, o cliente pede ao proxy para construir um túnel com o comando CONNECT. No HTTP comum não existe esse comando. Se o túnel não foi construído, chega esse erro, e ele só é possível em HTTPS.

Como diferenciar 403 do proxy de 403 do site?

Observe o corpo da resposta. Uma página bem formatada do site significa proibição do site. Uma página técnica ou menção ao proxy significa proibição do intermediário. Confirme com uma requisição direta ao site.

O que fazer em caso de quedas aleatórias de conexão?

Primeiro, determine a repetibilidade: faça uma série de requisições e conte a proporção de quedas. Quedas isoladas são instabilidade de rede tolerável. Quedas em massa são um problema sistêmico do proxy ou do canal.

Como compartilhar o log do curl -v com segurança para pedir ajuda?

Sempre apague a linha com a autorização do proxy e quaisquer cabeçalhos sensíveis antes de enviar. Caso contrário, você revela login e senha. Em caso de dúvida, troque os dados comprometidos.

Por que minhas requisições normais às vezes são cortadas por timeout?

Provavelmente, o read timeout está rígido demais, e você está cortando respostas lentas, mas saudáveis. Aumente o read timeout com folga e mantenha o connect timeout pequeno.

Onde ler sobre o código 429 e retries?

O código 429 e as estratégias de retry são um tema grande e separado, não relacionado diretamente a falhas da camada de proxy. Há um material dedicado a isso, estude-o separadamente do diagnóstico de erros de proxy.

Conclusão: o que você dominou e para onde ir agora

Parabéns. Você percorreu o caminho da perplexidade diante de códigos misteriosos até o diagnóstico passo a passo com segurança. Vamos relembrar o que agora está no seu arsenal.

Resumo das ações realizadas. Você aprendeu a dividir a cadeia em três elos — cliente, proxy e servidor — e a determinar onde exatamente surgiu o erro. Você entendeu o código 407 e a autorização de proxy, incluindo os traiçoeiros caracteres especiais na senha. Você compreendeu a natureza dupla do 502 e o método de verificação cruzada. Você dominou a separação de connect e read timeouts no 504. Você entendeu o método CONNECT e o erro tunnel connection failed em HTTPS. Você aprendeu a reconhecer as três causas de 403 do proxy e a diagnosticar quedas de conexão pela etapa. E, por fim, você dominou a principal habilidade — a leitura da saída do curl -v linha por linha, traçando com precisão as fronteiras entre os elos.

O que fazer a seguir. Fixe a habilidade na prática. Toda vez que encontrar um erro de proxy, não fique adivinhando, mas decomponha-o calmamente pelos elos com a ajuda da tabela de diagnóstico. Depois de uma semana dessa prática, o diagnóstico se tornará automático.

Para onde evoluir. O próximo passo lógico é estudar o tema do código 429 e das estratégias corretas de retry, ao qual é dedicado um material separado. Depois, aprofunde-se na classificação automática de erros no código e na coleta de métricas de estabilidade. Isso vai transformar você de alguém que apaga incêndios em um engenheiro que prevê problemas com antecedência.

Dica: Salve este guia e a tabela de diagnóstico nos seus favoritos. Volte a eles a cada novo erro, até que a lógica se torne sua segunda natureza. A confiança no diagnóstico vem justamente pela repetição. Você vai conseguir.