407 Proxy Authentication Required: Todas as Causas e Como Corrigir

HTTP 407 tem exatamente um significado: o proxy à sua frente recusou suas credenciais. Esse único fato elimina a maioria dos erros — aqui está o restante do mapa.

HTTP 407 Proxy Authentication Required tem exatamente um significado, e é mais restrito do que a maioria das pessoas supõe: um proxy entre você e a internet recusou a solicitação porque faltam credenciais válidas para o próprio proxy. O site de destino nunca foi contatado. Ele nunca viu sua solicitação, nunca tomou uma decisão e não pode ser a causa. Corrigir um 407, portanto, sempre significa corrigir sua configuração de proxy — e a lista de coisas que podem estar erradas com ela é curta e completamente enumerável. Este guia percorre toda a lista, com as correções específicas para ferramentas que mais confundem as pessoas.

Leia primeiro o cabeçalho Proxy-Authenticate

De acordo com a especificação HTTP (RFC 9110), um 407 deve ser acompanhado por um cabeçalho Proxy-Authenticate descrevendo como autenticar — tipicamente algo como Proxy-Authenticate: Basic realm="Access to internal site". Espera-se que seu cliente repita a solicitação com um cabeçalho Proxy-Authorization. Vale a pena memorizar esse emparelhamento, pois é o que distingue 407 de seu vizinho: um 401 vem do servidor de origem e emparelha WWW-Authenticate com Authorization, enquanto 407 vem de um intermediário e usa as versões prefixadas com Proxy-. Se você está olhando para um cabeçalho WWW-Authenticate, está depurando o salto errado.

# See exactly which hop is refusing you, and what scheme it wants
curl -v -x http://USER:PASS@gate.quantumproxies.io:8000 https://httpbin.org/ip

# Response you are looking for on failure:
#   HTTP/1.1 407 Proxy Authentication Required
#   Proxy-Authenticate: Basic realm="..."
#
# Response you want on success: your exit IP, not your own
#   {"origin": "203.0.113.45"}

Se curl -x com credenciais retorna seu IP de saída, o proxy e as credenciais estão ambos corretos — e qualquer 407 que você ainda veja em uma aplicação é a própria configuração da aplicação, não do proxy. Esse único teste divide o problema ao meio em cerca de dez segundos.

Causa 1: as credenciais estão ausentes, erradas ou no lugar errado

A causa mais comum é também a mais tediosa. As credenciais pertencem ao URL do proxy, antes do host, na forma user:pass@host:port — e a biblioteca cliente constrói o cabeçalho Proxy-Authorization a partir delas. Copiar um endpoint de um painel sem as credenciais, ou colar sua senha de conta em vez da senha do proxy (elas geralmente são diferentes), produz um 407 imediato e permanente em cada solicitação.

import requests

proxy = "http://USER:PASS@gate.quantumproxies.io:8000"
proxies = {"http": proxy, "https": proxy}

r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=15)
print(r.status_code, r.json())   # 200 and the exit IP = auth is correct

Verifique a porta também. Os provedores expõem portas diferentes para endpoints rotativos e fixos, e para HTTP versus SOCKS5; acessar a porta errada com credenciais válidas ainda pode retornar 407 porque esse ouvinte espera um formato de identidade diferente. Se você não tem certeza de qual protocolo está usando, nosso explicador sobre SOCKS5 versus proxies HTTP descreve as diferenças.

Causa 2: caracteres especiais que nunca foram codificados percentualmente

Este custa tardes inteiras às pessoas. Um URL de proxy é um URL, então qualquer caractere reservado em seu nome de usuário ou senha deve ser codificado percentualmente ou o analisador dividirá a string no lugar errado. Uma senha contendo @ termina a seção de informações do usuário cedo e seu cliente tenta se conectar a um host que não existe; um : divide o nome de usuário da senha no lugar errado.

from urllib.parse import quote

user = quote("team@example.com", safe="")   # team%40example.com
pwd  = quote("p@ss:w#rd", safe="")          # p%40ss%3Aw%23rd

proxy = f"http://{user}:{pwd}@gate.quantumproxies.io:8000"
Lista de verificação mapeando sintomas de 407 proxy authentication required para suas causas reais, incluindo falhas de túnel, mudanças de lista branca e configurações de proxy por ferramenta
Mesmo código de status, seis falhas diferentes. Combine o sintoma à esquerda antes de mudar qualquer coisa.

Causa 3: autenticação por lista branca e um IP que mudou

A maioria dos provedores suporta dois modos de autenticação: credenciais no URL ou lista branca de IP, onde você autoriza o endereço público do seu servidor no painel e não envia credenciais. QuantumProxies suporta ambos. O modo de falha é específico e muito reconhecível: tudo funcionou por semanas, então cada solicitação começou a retornar 407 sem uma mudança de código. Isso é seu IP público mudando — uma renovação de concessão DHCP no escritório, um novo gateway NAT após uma reimplantação na nuvem, uma conexão móvel ou um executor de CI que obtém um novo endereço em cada trabalho.

Confirme isso antes de depurar qualquer outra coisa: obtenha seu endereço público atual com curl -sS https://api.ipify.org, compare-o com a lista branca e adicione-o novamente se for diferente. Se seu IP de saída não for estável — executores de CI e grupos de escalonamento automático raramente são — mude esse ambiente para autenticação user:pass, que viaja com a configuração em vez da rede. A outra metade desta armadilha é misturar modos: alguns gateways rejeitam credenciais em um endpoint apenas de lista branca, então enviar ambos pode falhar onde enviar nenhum tem sucesso.

Causa 4: HTTPS passa por um túnel CONNECT

Um 407 que aparece apenas em URLs https://, muitas vezes como o erro Python OSError: Tunnel connection failed: 407 Proxy Authentication Required, tem uma causa estrutural. Solicitações HTTP simples são encaminhadas pelo proxy, mas solicitações HTTPS abrem um túnel primeiro com uma solicitação CONNECT — e esse CONNECT carrega seu próprio cabeçalho Proxy-Authorization. Se sua configuração apenas definiu um proxy HTTP, ou definiu credenciais em um esquema e não no outro, o túnel é tentado anonimamente e recusado antes mesmo de o TLS começar.

A regra é simples: sempre configure ambos os esquemas com as mesmas credenciais. Em Python, isso significa ambas as chaves no dicionário proxies; no shell, significa HTTP_PROXY e HTTPS_PROXY; no npm, significa proxy e https-proxy. Note que HTTPS_PROXY quase sempre usa um esquema http:// — o esquema descreve como você fala com o proxy, não o que você está buscando através dele.

// Node 18+ with undici: one dispatcher covers http and https targets
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent(
  "http://USER:PASS@gate.quantumproxies.io:8000"
);

const res = await fetch("https://httpbin.org/ip", { dispatcher });
console.log(res.status, await res.json());

Causa 5: a ferramenta tem sua própria configuração de proxy

Variáveis de ambiente não são universais. Muitas ferramentas leem seu próprio arquivo de configuração e ignoram completamente o shell, o que produz o estado enlouquecedor onde curl funciona e sua build não. Um problema de longa data no GitHub Desktop é a ilustração clássica: um desenvolvedor atrás de um proxy corporativo havia configurado o proxy em .gitconfig e no ambiente, mas o login ainda falhava com um 407 e net::ERR_TUNNEL_CONNECTION_FAILED — porque a configuração do git apenas autenticava o git, enquanto o navegador embutido fazendo o fluxo OAuth não tinha suas próprias credenciais de proxy. Cada subsistema precisa ser informado separadamente.

# shell-wide (respected by curl, wget, pip, most SDKs)
export HTTP_PROXY="http://USER:PASS@gate.quantumproxies.io:8000"
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal"

# npm - both keys, or https installs will 407
npm config set proxy       "$HTTP_PROXY"
npm config set https-proxy  "$HTTPS_PROXY"

# git
git config --global http.proxy  "$HTTP_PROXY"
git config --global https.proxy "$HTTPS_PROXY"

# apt - /etc/apt/apt.conf.d/95proxies
# Acquire::http::Proxy  "http://USER:PASS@gate.quantumproxies.io:8000";
# Acquire::https::Proxy "http://USER:PASS@gate.quantumproxies.io:8000";

Uma nota de segurança enquanto você edita todos esses arquivos: credenciais em um git ou npm config global acabam em texto simples, e URLs de proxy com senhas embutidas vazam para o histórico do shell, logs de CI e rastreamentos de erro. Em máquinas com um endereço estável, a lista branca de IP evita o segredo completamente.

Comparação de autenticação de proxy user:pass versus autenticação por lista branca de IP, mostrando trade-offs de portabilidade e manuseio de segredos
Credenciais viajam com sua configuração; listas brancas viajam com sua rede. Escolha por ambiente, nunca ambos ao mesmo tempo.

Um 407 nunca é culpa do site de destino

Vale a pena repetir, porque isso te salva de perseguir fantasmas. Se você está recebendo 407s, nenhuma quantidade de rotação de user agents, adição de cabeçalhos ou mudança de países de saída ajudará — a solicitação ainda não deixou seu proxy. Bloqueios que vêm do destino parecem diferentes: um 403 Forbidden significa que o site te recusou, e um 429 Too Many Requests significa que você foi rápido demais. Diagnostique qual dos três você realmente tem antes de escrever qualquer código. E se Python estiver lançando ProxyError ou SSLError em vez de um 407 limpo, nosso guia para depurar ProxyError em Requests cobre as falhas de nível de transporte.

Perguntas frequentes

Como resolvo 407 Proxy Authentication Required?

Coloque credenciais válidas no URL do proxy como http://user:pass@host:port, codificando percentualmente quaisquer caracteres reservados, e configure as configurações de proxy HTTP e HTTPS. Se seu provedor usa lista branca de IP em vez disso, autorize seu IP público atual e não envie credenciais. Verifique com curl -x contra um serviço de eco de IP antes de mexer no código da sua aplicação.

O que significa 407 Proxy Authentication Required?

Significa que um proxy intermediário recusou a solicitação por falta de credenciais de proxy válidas. A resposta inclui um cabeçalho Proxy-Authenticate nomeando o esquema, e espera-se que o cliente tente novamente com Proxy-Authorization. É distinto de 401, que vem do servidor de destino em vez do proxy intermediário.

Como corrijo o erro npm 407?

Defina ambas as chaves: npm config set proxy e npm config set https-proxy, cada uma com o URL completo http://user:pass@host:port. O tráfego do registro é HTTPS, então uma configuração apenas HTTP falha no túnel CONNECT. Codifique percentualmente caracteres especiais na senha e verifique se há um .npmrc em nível de projeto que sobrepõe o global.

Por que Python gera Tunnel connection failed: 407?

Porque a solicitação HTTPS abriu um túnel CONNECT que não carregou credenciais de proxy. Defina ambas as chaves http e https do dicionário proxies para o mesmo URL autenticado. Também verifique se HTTP_PROXY ou HTTPS_PROXY no ambiente está sobrepondo seu dicionário — defina session.trust_env = False para descartar isso.

Como configuro autenticação de proxy no Postman?

Abra Configurações, vá para a guia Proxy, habilite a configuração de proxy personalizada, insira host e porta, depois marque a caixa de autenticação de proxy e adicione o nome de usuário e a senha. Confiar na alternância de proxy do sistema é o erro usual — ele roteia o tráfego através do proxy, mas nunca fornece credenciais, então cada solicitação retorna 407.

Cinco causas cobrem essencialmente todos os 407s na prática: credenciais ausentes, caracteres especiais não codificados, um IP em lista branca que mudou, um túnel CONNECT não autenticado e uma ferramenta com sua própria configuração. Trabalhe com elas nessa ordem e o código de status desaparece — então você pode começar a se preocupar com o que o site de destino pensa de você.

Obtenha proxies residenciais com autenticação user:pass ou lista branca de IP