Referência de erro de proxy · Códigos de status HTTP

407 Proxy Authentication Required: o que significa e como corrigir

Código de status HTTP (4xx, erro do cliente): a mensagem exata em cada ferramenta, as causas prováveis em ordem, e o conserto que funciona.

Última atualização: 13 de outubro de 2026 · 6 min de leitura

Resposta rápida

O que 407 Proxy Authentication Required significa com um proxy?

407 Proxy Authentication Required significa que o proxy recusou sua solicitação porque não recebeu credenciais ou recebeu incorretas. O site alvo nunca foi contatado. Com proxies residenciais CrawlRelay, verifique três coisas: o nome de usuário é o exibido no seu painel, a senha corresponde, e qualquer caractere especial em algum deles está codificado em URL. Tentar a mesma solicitação novamente nunca resolve um 407.

407 Proxy Authentication Required de relance

Erro	407 Proxy Authentication Required
Tipo	Código de status HTTP (4xx, erro do cliente)
Enviado por	O gateway proxy, nunca o site alvo
Definido em	RFC 9110, section 15.5.8 (headers: Proxy-Authenticate 11.7.1, Proxy-Authorization 11.7.2)
Tentar novamente?	Não. As mesmas credenciais falham novamente; corrija-as primeiro
Primeira verificação	Execute o teste curl abaixo com apenas o nome de usuário e sem parâmetros de direcionamento

O que 407 Proxy Authentication Required significa?

Um 407 vem do proxy, não do site que você deseja acessar. RFC 9110 o descreve como a versão do proxy do 401: o cliente deve autenticar-se com o proxy antes de qualquer outra coisa. O proxy envia um cabeçalho Proxy-Authenticate que indica o esquema aceito, quase sempre Basic. Seu cliente responde com um cabeçalho Proxy-Authorization que carrega username:password codificado em Base64.

Para um alvo HTTPS, o 407 chega em resposta ao pedido CONNECT que abre o túnel. Por isso muitas bibliotecas reportam isso como erro de conexão ou túnel, e não como status HTTP: a sessão TLS com o site nunca foi iniciada.

Como a 407 aparece em Python, curl, Node.js e navegadores?

A mesma falha aparece de forma diferente em cada ferramenta. Estas são as mensagens para buscar nos seus logs:

Python requests: ProxyError('Unable to connect to proxy', OSError('Tunnel connection failed: 407 Proxy Authentication Required'))
curl: curl: (56) CONNECT tunnel failed, response 407
Scrapy: TunnelError: Could not open CONNECT tunnel with proxy ... [{'status': 407, 'reason': b'Proxy Authentication Required'}]
Chrome, Playwright, Puppeteer: net::ERR_TUNNEL_CONNECTION_FAILED, ou um pop-up de login em um navegador visível
Node.js clientes em um alvo http://: Request failed with status code 407

O que causa a 407?

Mais provável inicialmente:

Nome de usuário ou senha errados. Um erro de digitação, uma senha antiga após reset, ou as credenciais de outro subusuário.
Caracteres especiais não codificados. Senha contendo @, :, / ou # quebra a URL user:pass@host. Codifique porcentagem: @ vira %40, : vira %3A.
Sufixo de direcionamento quebrado. Gateways que leem direcionamento do nome de usuário veem uma string longa como um nome só. Um erro em uma chave ou código de país vira um nome de usuário que o proxy não conhece.
Credenciais nunca saem do seu código. Chrome ignora nome de usuário e senha escritos dentro de --proxy-server. Puppeteer precisa de page.authenticate(), e Selenium precisa de um encaminhador local.
Saldo vazio. Verifique se sua conta ainda tem tráfego antes de depurar o código.

Como diagnosticar a 407 passo a passo?

Teste as credenciais com curl e sem direcionamento algum (comando abaixo). Uma linha HTTP/1.1 407 na saída detalhada confirma problema nas credenciais.
Reintroduza seus parâmetros de direcionamento um por um, executando o teste após cada um.
Registre a URL do proxy que seu programa efetivamente monta, com a senha mascarada, e compare caractere por caractere com o painel.
Se o curl funciona e seu programa falha, a biblioteca não está enviando as credenciais. Leia a correção para sua ferramenta abaixo.

Teste a URL com erro usando curl (porta HTTP, modo verbose)

# Use the URL that fails; with https://api.ipify.org instead, you test the gateway alone.
# "HTTP/1.1 200 Connection established" first, then the site's own status: the site answered.
curl -v -x http://USERNAME:[email protected]:7777 https://TARGET_URL

# Same test through the SOCKS5 port, with DNS resolved at the exit
curl -v --socks5-hostname gw.crawlrelay.com:7778 --proxy-user USERNAME:PASSWORD https://TARGET_URL

Como corrigir a 407?

Codifique as credenciais com urllib.parse.quote(value, safe='') em Python ou encodeURIComponent() em JavaScript antes de montar a URL.
Navegadores: passe username e password na opção proxy do Playwright, chame page.authenticate() no Puppeteer e use um encaminhador local para Selenium. Veja os guias Playwright e Puppeteer.
Variáveis de ambiente: se configurar HTTPS_PROXY, coloque o valor todo entre aspas no shell para que @ e $ sobrevivam.
Altere a senha no painel se suspeitar de vazamento e atualize todos os scrapers que a usam.

Python: construa a URL do proxy com credenciais codificadas

from urllib.parse import quote

import requests

user = "USERNAME-country-us"
password = "p@ss:word/1"  # example containing special characters

# safe="" also encodes "/", "@" and ":" inside the credentials
proxy = "http://{}:{}@gw.crawlrelay.com:7777".format(
    quote(user, safe=""), quote(password, safe="")
)
proxies = {"http": proxy, "https": proxy}  # http:// for both keys

r = requests.get("https://api.ipify.org", proxies=proxies, timeout=(10, 30))
print(r.status_code, r.text)

Playwright (Python): credenciais como campos separados

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server": "http://gw.crawlrelay.com:7777",
        "username": "USERNAME-country-us",
        "password": "PASSWORD",
    })
    page = browser.new_page()
    response = page.goto("https://api.ipify.org")
    print(response.status, page.inner_text("body"))
    browser.close()

Devo tentar novamente após a 407?

Não tente novamente um 407 automaticamente. Retentar com as mesmas credenciais retorna a mesma resposta, e um loop apertado só enche seus logs. Trate 407 como erro de configuração: pare o trabalho, corrija as credenciais e reinicie. Se 407 surgir de repente em um trabalho que rodava há dias, provavelmente a senha foi alterada ou subusuário desativado.

Como 407 Proxy Authentication Required se aplica ao CrawlRelay?

O gateway CrawlRelay lê o nome de usuário e senha a cada nova conexão. Configurações de direcionamento e sessão vivem no nome de usuário, então uma senha válida pode falhar se o sufixo estiver malformado. Monte o nome de usuário em uma função auxiliar e registre seu resultado uma vez na inicialização. A página de início rápido mostra o formato exato.

Gateway: gw.crawlrelay.com, porta 7777 (HTTP, HTTPS via CONNECT) e porta 7778 (SOCKS5). Formato do usuário: USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}. Relacionado: 401 vs 407 · ERR_TUNNEL_CONNECTION_FAILED · Cannot connect to proxy.

407 Proxy Authentication Required: perguntas que desenvolvedores fazem

Um 407 é enviado pelo site que estou raspando?

Não. Um 407 é sempre enviado por um proxy que fica entre você e o site. A solicitação nunca atingiu o site, que não vê nem conta seu tráfego, nem bloqueia por ele. Se o site quisesse login, responderia 401. Corrija as credenciais do proxy e o 407 some.

Por que meu código recebe 407 enquanto curl funciona com o mesmo proxy?

Sua biblioteca não está enviando as credenciais, ou envia em formato diferente. Causas comuns são credenciais digitadas em flag de navegador que as ignora, variável de ambiente que perdeu caracteres especiais, ou senha não codificada em URL. Imprima a URL do proxy que seu código monta, com senha mascarada, e compare com o comando curl.

Um 407 consome tráfego do meu plano?

Uma resposta 407 tem poucas centenas de bytes, e o pedido nunca chega ao alvo, então nenhuma página é baixada. O custo está em outro lugar: um scraper preso em loop de tentativas 407 perde tempo e enche seus logs. Faça do 407 uma parada obrigatória no tratamento de erros.

Outros erros de proxy nesta referência

Códigos de status HTTP

Erros no navegador e cliente

Erros de conexão e TLS

Proxies residenciais com documentação que cobre os casos de falha

CrawlRelay proxies residenciais a partir de US$ 0,50/GB, tráfego que nunca expira.

Veja os preços Início rápido