# ProxyError: 'Não foi possível conectar ao proxy' em Python e Node.js

> requests.exceptions.ProxyError 'Não foi possível conectar ao proxy', explicado: leia a causa aninhada (recusado, timeout, DNS, 407, 502) e aplique a solução correta.

- URL: https://crawlrelay.com/pt/docs/errors/cannot-connect-to-proxy/
- Última atualização: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Erro na biblioteca cliente (Python, Node.js): a mensagem exata em cada ferramenta, as causas prováveis em ordem, e o conserto que funciona.

**Resposta rápida — O que Cannot connect to proxy (ProxyError) significa com um proxy?**

**'Não foi possível conectar ao proxy'** é um erro genérico: requests e urllib3 do Python colocam a causa real dentro dele. Leia a causa mais interna. 'Conexão recusada' ou timeout significa problema no host, porta ou rede; 'Falha na resolução' indica DNS; 'Falha na conexão do túnel: 407' indica credenciais. Com CrawlRelay, cada um tem uma solução rápida.

## Cannot connect to proxy (ProxyError) de relance

| Atributo | Valor |
| --- | --- |
| Erro | Cannot connect to proxy (ProxyError) |
| Tipo | Erro na biblioteca cliente (Python, Node.js) |
| Enviado por | Seu cliente HTTP, antes ou enquanto conversa com o proxy |
| Definido em | Library error; read the nested cause for the real reason |
| Tentar novamente? | Depende da causa aninhada |
| Primeira verificação | Leia a exceção mais interna: recusado, timeout, resolução de nome ou código de status |

## O que Cannot connect to proxy (ProxyError) significa?

urllib3 gera um `ProxyError` para cada falha relacionada ao proxy, e requests repassa. A informação útil está na exceção aninhada, impressa ao final da longa linha do traceback.

Node.js clientes se comportam diferente: reportam diretamente o erro de socket, como `ECONNREFUSED` ou `ETIMEDOUT`, muitas vezes sem indicar que o endereço era do proxy.

## Como 'Cannot connect to proxy' 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:

- **Recusado:** `ProxyError('Unable to connect to proxy', NewConnectionError(... Connection refused))`
- **DNS:** `NameResolutionError(... Failed to resolve ...)` dentro de `ProxyError`
- **Credenciais:** `OSError('Tunnel connection failed: 407 Proxy Authentication Required')`
- **Erro de gateway:** `OSError('Tunnel connection failed: 502 Bad Gateway')`
- **Node.js:** `Error: connect ECONNREFUSED`, `ETIMEDOUT` ou `ENOTFOUND`, seguido pelo endereço do proxy

## O que causa 'Cannot connect to proxy'?

Mais provável inicialmente:

- **Host ou porta incorretos** na URL do proxy.
- **Falta o esquema:** `host:port` sem `http://` é interpretado de forma inesperada por algumas bibliotecas.
- **Tráfego de saída bloqueado** na sua rede ou servidor.
- **Erros de credenciais ou gateway** durante a etapa CONNECT, agrupados na mesma exceção.
- **Variáveis de ambiente** como `HTTPS_PROXY` que apontam para um proxy antigo e sobrescrevem seu código.

## Como diagnosticar 'Cannot connect to proxy' passo a passo?

1. Imprima a exceção completa e leia a causa aninhada mais interna.
2. Imprima as variáveis `requests.utils.get_environ_proxies(url)` ou `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY` para conferir o que está configurado.
3. Rode o teste curl abaixo na mesma máquina.
4. Compare a causa com a lista de soluções a seguir.

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

```bash
# 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:PASSWORD@gw.crawlrelay.com: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 'Cannot connect to proxy'?

- **Recusado ou timeout:** corrija o host e a porta, ou libere o tráfego de saída para o gateway.
- **Falha ao resolver:** verifique o DNS na máquina; tente o host com `nslookup`.
- **407:** corrija e codifique em URL as credenciais. Veja [407 Proxy Authentication Required](https://crawlrelay.com/pt/docs/errors/407-proxy-authentication-required/).
- **502 ou 504:** tente novamente em um novo ponto de saída. Veja [502](https://crawlrelay.com/pt/docs/errors/502-bad-gateway/) e [504](https://crawlrelay.com/pt/docs/errors/504-gateway-timeout/).
- **Proxy de ambiente indesejado:** defina `session.trust_env = False` no requests ou limpe as variáveis.

*Python: construa a URL do proxy com credenciais codificadas*

```python
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)
```

## Devo tentar novamente após 'Cannot connect to proxy'?

Retente apenas as causas na camada de rede que podem variar: timeouts e erros de gateway como 502 ou 504. Conexão recusada, falha DNS ou 407 repetirão até mudar a configuração, então trate como erro fatal.

## Como Cannot connect to proxy (ProxyError) se aplica ao CrawlRelay?

Para CrawlRelay, a URL do proxy é `http://USERNAME:PASSWORD@` seguida pelo host do gateway e porta HTTP listados abaixo, para alvos HTTP e HTTPS. Use a mesma URL `http://` para as chaves `http` e `https` em requests: o esquema indica o protocolo falado com o proxy, não com o site.

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: [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/pt/docs/errors/ssl-wrong-version-number/) · [407](https://crawlrelay.com/pt/docs/errors/407-proxy-authentication-required/) · [Guia Python](https://crawlrelay.com/pt/docs/python/).

## Cannot connect to proxy (ProxyError): perguntas que desenvolvedores fazem

### O que significa 'Max retries exceeded with url' com proxy?

Significa que urllib3 desistiu após a cota de tentativas, e a causa real segue na parte 'Causado por' da mensagem. Com proxy, normalmente é um ProxyError com causa aninhada: conexão recusada, timeout, falha na resolução de nome ou status de túnel tipo 407.

### Por que requests usa um proxy que eu não configurei?

requests lê as variáveis de ambiente `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY` por padrão, e no Windows lê também as configurações de proxy do sistema. Um valor residual sobrescreve suas expectativas. Defina `session.trust_env = False`, ou passe os proxies explicitamente em cada requisição.

### Devo colocar http:// ou https:// antes do endereço do proxy?

Escreva `http://` para proxy HTTP, mesmo que o site use HTTPS. O esquema define como seu cliente conversa com o proxy. Usar `https://` faz urllib3 versões recentes iniciar TLS com o proxy, falhando em porta HTTP com erro SSL.

## Outros erros de proxy nesta referência

- [401 Unauthorized vs 407](https://crawlrelay.com/pt/docs/errors/401-unauthorized/)
- [403 Forbidden](https://crawlrelay.com/pt/docs/errors/403-forbidden/)
- [407 Proxy Authentication Required](https://crawlrelay.com/pt/docs/errors/407-proxy-authentication-required/)
- [429 Too Many Requests](https://crawlrelay.com/pt/docs/errors/429-too-many-requests/)
- [502 Bad Gateway](https://crawlrelay.com/pt/docs/errors/502-bad-gateway/)
- [503 Service Unavailable](https://crawlrelay.com/pt/docs/errors/503-service-unavailable/)
- [504 Gateway Timeout](https://crawlrelay.com/pt/docs/errors/504-gateway-timeout/)
- [Cannot connect to proxy (ProxyError)](https://crawlrelay.com/pt/docs/errors/cannot-connect-to-proxy/)
- [Connection reset by peer (ECONNRESET)](https://crawlrelay.com/pt/docs/errors/connection-reset/)
- [ERR_PROXY_CONNECTION_FAILED](https://crawlrelay.com/pt/docs/errors/err-proxy-connection-failed/)
- [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/pt/docs/errors/err-tunnel-connection-failed/)
- [Read timed out (ReadTimeout)](https://crawlrelay.com/pt/docs/errors/read-timeout/)
- [SOCKS5 proxy errors](https://crawlrelay.com/pt/docs/errors/socks5-proxy-errors/)
- [SSL: CERTIFICATE_VERIFY_FAILED](https://crawlrelay.com/pt/docs/errors/ssl-certificate-verify-failed/)
- [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/pt/docs/errors/ssl-wrong-version-number/)

**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](https://crawlrelay.com/pt/pricing/) · [Início rápido](https://crawlrelay.com/pt/docs/)

---

CrawlRelay: CrawlRelay é um serviço proxy residencial rotativo e proxies móveis 4G/5G para desenvolvedores, para scrapers e pipelines de dados de IA: tráfego pay-as-you-go que não expira a partir de US$ 0,50/GB, pago com cripto, sem upload de documento. Sem KYC — sem ID, sem selfie, sem documentos. Pague com cripto.