# ProxyError: Python에서 '프록시 연결 불가' 및 Node.js

> requests.exceptions.ProxyError '프록시에 연결할 수 없음' 문제 설명: 중첩된 원인(거부, 타임아웃, DNS, 407, 502)을 읽고 적절한 해결책을 적용하세요.

- URL: https://crawlrelay.com/ko/docs/errors/cannot-connect-to-proxy/
- 마지막 업데이트: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

클라이언트 라이브러리 오류 (Python, Node.js): 각 도구에서 정확한 메시지, 가능한 원인들의 순서, 그리고 효과적인 해결 방법.

**빠른 답변 — 프록시에서 Cannot connect to proxy (ProxyError)는 무엇을 의미하나요?**

**'프록시 연결 불가'**는 래퍼 오류입니다: Python의 requests와 urllib3가 실제 원인을 내부에 담고 있습니다. 가장 안쪽 원인을 확인하세요. '연결 거부됨' 또는 시간 초과는 호스트, 포트 또는 네트워크 문제를 뜻하며; '해결 실패'는 DNS 문제; '터널 연결 실패: 407'은 인증 정보 문제입니다. CrawlRelay에서는 각각을 한 줄로 해결할 수 있습니다.

## Cannot connect to proxy (ProxyError) 한눈에 보기

| 속성 | 값 |
| --- | --- |
| 오류 | Cannot connect to proxy (ProxyError) |
| 유형 | 클라이언트 라이브러리 오류 (Python, Node.js) |
| 전송 주체 | 프록시와 통신 중 또는 전 HTTP 클라이언트 |
| 정의 위치 | Library error; read the nested cause for the real reason |
| 다시 시도할까요? | 중첩된 원인에 따라 다름 |
| 먼저 확인하세요 | 중첩 예외를 읽으세요: 거부, 타임아웃, 이름 확인 실패 또는 상태 코드 |

## Cannot connect to proxy (ProxyError)가 무엇을 의미하나요?

urllib3는 프록시와 관련된 실패마다 하나의 `ProxyError`를 발생시키며, requests가 이를 전달합니다. 유용한 정보는 중첩 예외에 있으며, traceback이 긴 줄 끝에서 출력합니다.

Node.js 클라이언트는 다르게 동작합니다: 소켓 오류(예: `ECONNREFUSED` 또는 `ETIMEDOUT`)를 직접 보고하지만, 주소가 프록시임을 명시하지 않는 경우가 많습니다.

## Python, curl, Node.js, 브라우저에서 'Cannot connect to proxy'는 어떻게 나타나나요?

같은 실패가 도구마다 다르게 출력됩니다. 로그에서 검색할 메시지들:

- **거부됨:** `ProxyError('Unable to connect to proxy', NewConnectionError(... Connection refused))`
- **DNS:** `NameResolutionError(... Failed to resolve ...)`가 `ProxyError` 내에 있음
- **인증 정보:** `OSError('Tunnel connection failed: 407 Proxy Authentication Required')`
- **게이트웨이 오류:** `OSError('Tunnel connection failed: 502 Bad Gateway')`
- **Node.js:** `Error: connect ECONNREFUSED`, `ETIMEDOUT` 또는 `ENOTFOUND`, 뒤이어 프록시 주소

## 'Cannot connect to proxy'의 원인은 무엇인가요?

가장 가능성 높은 첫 번째 원인:

- **프록시 URL의 잘못된 호스트 또는 포트**
- **스킴 누락:** 일부 라이브러리가 `host:port`에 `http://`가 없으면 의외의 방식으로 해석함
- **네트워크 또는 서버의 아웃바운드 트래픽 차단**
- **CONNECT 단계에서 발생하는 인증 또는 게이트웨이 오류**가 동일 예외로 감싸져 발현됨
- **`HTTPS_PROXY` 같은 환경 변수**가 이전 프록시를 가리키며 코드 설정을 덮어씀

## 'Cannot connect to proxy'를 단계별로 진단하는 방법은?

1. 전체 예외를 출력하고 마지막 중첩 원인 확인
2. `requests.utils.get_environ_proxies(url)` 또는 `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` 환경 변수 출력하여 추가 설정 확인
3. 동일 기기에서 아래 curl 테스트 실행
4. 원인을 아래 해결법 목록과 비교

*curl로 실패한 URL 테스트하기(HTTP 포트, 상세 모드)*

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

## 'Cannot connect to proxy'를 어떻게 고치나요?

- **거부됨 또는 시간 초과:** 호스트와 포트를 수정하거나 게이트웨이로의 아웃바운드 트래픽을 열기
- **해결 실패:** 기기에서 DNS 점검; `nslookup`로 호스트 시도
- **407:** 인증 정보를 수정하고 URL 인코딩; [407 Proxy Authentication Required](https://crawlrelay.com/ko/docs/errors/407-proxy-authentication-required/) 참조]
- **502 또는 504:** 새 출구 노드에서 재시도; [502](https://crawlrelay.com/ko/docs/errors/502-bad-gateway/)], [504](https://crawlrelay.com/ko/docs/errors/504-gateway-timeout/) 참조]
- **원치 않는 환경 프록시:** requests에 `session.trust_env = False` 설정하거나 환경 변수 정리

*Python: 인코딩된 자격 증명으로 프록시 URL 빌드하기*

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

## 'Cannot connect to proxy' 이후에 다시 시도해야 하나요?

변경 가능한 네트워크 레벨 원인(시간 초과, 502/504 같은 게이트웨이 오류)만 재시도하세요. 연결 거부, DNS 실패, 407은 설정 변경 전까지 반복 발생하므로 치명적 오류로 처리하세요.

## Cannot connect to proxy (ProxyError)가 CrawlRelay에 어떻게 적용되나요?

CrawlRelay에서는 HTTP 및 HTTPS 대상 모두에 대해 `http://USERNAME:PASSWORD@` 뒤에 아래 게이트웨이 호스트 및 HTTP 포트를 붙여 프록시 URL을 구성합니다. requests의 `http`와 `https` 키에 동일한 `http://` URL을 사용하세요: 스킴은 사이트가 아닌 프록시와 통신하는 프로토콜을 지정합니다.

게이트웨이: `gw.crawlrelay.com`, 포트 7777 (CONNECT를 통한 HTTP, HTTPS) 및 포트 7778 (SOCKS5). 사용자 이름 형식: `USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}`. 관련: [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/ko/docs/errors/ssl-wrong-version-number/) · [407](https://crawlrelay.com/ko/docs/errors/407-proxy-authentication-required/) · [Python 가이드](https://crawlrelay.com/ko/docs/python/).

## Cannot connect to proxy (ProxyError): 개발자들이 묻는 질문들

### 프록시에서 'Max retries exceeded with url' 메시지는 무슨 뜻인가요?

이는 urllib3가 재시도 한도 초과 후 포기했다는 의미이며, 이유는 메시지의 'Caused by' 부분에 나옵니다. 프록시가 있다면 그 부분은 보통 ProxyError이고, 중첩 원인은 연결 거부, 시간 초과, 이름 해석 실패 또는 407 같은 터널 상태입니다.

### 내가 설정하지 않은 프록시를 requests가 왜 사용하나요?

requests는 기본적으로 `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` 환경 변수를 읽으며 Windows에서는 시스템 프록시 설정도 참조합니다. 남아 있는 설정값이 예상과 다르게 동작하게 합니다. `session.trust_env = False`를 설정하거나 요청마다 프록시를 명시적으로 지정하세요.

### 프록시 주소 앞에 http:// 또는 https://를 붙여야 하나요?

웹사이트가 HTTPS라도 HTTP 프록시일 경우 `http://`를 씁니다. 스킴은 클라이언트가 프록시와 통신하는 방식을 설명합니다. `https://`로 쓰면 최신 urllib3가 프록시에 TLS 시작을 시도해 HTTP 포트에 SSL 오류가 납니다.

## 이 참조에서 다른 프록시 오류들

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

**실패 사례를 다루는 문서가 있는 레지덴셜 프록시들** US$0.50/GB의 레지덴셜 프록시 CrawlRelay개, 트래픽이 절대 만료되지 않음. [가격 확인](https://crawlrelay.com/ko/pricing/) · [빠른 시작](https://crawlrelay.com/ko/docs/)

---

CrawlRelay: CrawlRelay는 개발자 중심의 회전형 레지덴셜 프록시 및 4G/5G 모바일 프록시 서비스로, 스크래퍼와 AI 데이터 파이프라인을 위한 비만료 선불 과금 트래픽을 US$0.50/GB부터 암호화폐로 결제하며 신분증 업로드가 없습니다. KYC 없이 — 신분증, 셀카, 문서 없이 이용 가능. 암호화폐로 결제하세요.