# 연결 및 네트워크 문제

> YesCaptcha API에 연결되지 않을 때 대처법. Failed to establish a new connection, DNS 확인 실패, 프록시 소프트웨어 간섭, SSL 인증서 오류(Certificate has expired, SSLEOFError)의 점검 절차를 안내해요.

Source: https://docs.yescaptcha.com/ko/help/troubleshooting/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/troubleshooting/

API를 호출할 때 연결 오류(예: `Failed to establish a new connection`, `getaddrinfo failed`, 타임아웃, SSL 오류)가 발생한다면 대개 로컬 네트워크, DNS, 프록시 소프트웨어가 원인이에요. 아래 순서대로 점검하세요.

## 1\. 다른 엔드포인트로 시도하기

YesCaptcha에는 `https://api.yescaptcha.com`(글로벌)과 `https://cn.yescaptcha.com`(중국) 두 개의 엔드포인트가 있어요. 중국 본토 서버에서는 중국 엔드포인트를, 그 외 지역에서는 글로벌 엔드포인트를 사용하세요. 엔드포인트를 바꿨다면 결과 조회도 같은 엔드포인트로 해야 해요.

```bash
curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
```

둘 중 하나라도 JSON을 반환하면 네트워크는 정상이고, 다른 엔드포인트로 가는 회선에 문제가 있는 거예요.

## 2\. 프록시 소프트웨어 확인하기

YesCaptcha에 접속하는 데 프록시는 필요하지 않아요. 컴퓨터에서 프록시나 VPN 소프트웨어를 실행 중이라면:

-   먼저 끄고 다시 시도하세요.
-   꼭 켜 두어야 한다면 전역 모드 대신 규칙 기반 분류(PAC 모드)로 바꾸거나, `api.yescaptcha.com`과 `cn.yescaptcha.com`을 직접 연결 목록에 추가하세요.
-   프록시를 켠 상태에서 Python이 `SSLEOFError(8, 'EOF occurred in violation of protocol')`를 반환하는 것도 대부분 프록시 때문이에요. 프록시를 끄거나 이 두 도메인을 직접 연결하면 해결돼요.

## 3\. 네트워크와 DNS 확인하기

```bash
ping api.yescaptcha.com
```

-   호스트를 찾을 수 없다고 나오는 경우: DNS 확인에 실패한 거예요. DNS 캐시를 초기화하거나(Windows: `ipconfig /flushdns`, macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`), 컴퓨터의 DNS를 공용 DNS(예: `223.5.5.5`, `119.29.29.29`, `8.8.8.8`)로 바꾼 뒤 다시 시도하세요.
-   ping은 실패하지만 주소는 확인되는 경우: 네트워크에서 ICMP를 차단했을 수 있어요. API에 접속할 수 없다는 뜻은 아니므로 1단계의 curl 결과를 기준으로 판단하세요.

## 4\. SSL 인증서 오류

-   `Certificate has expired` 또는 `certificate verify failed`가 나오는 경우: 먼저 컴퓨터의 **시스템 시간**이 정확한지 확인하세요. 그다음 운영체제, Python의 `certifi`, Postman 등의 도구를 최신 버전으로 업데이트해서 최신 루트 인증서를 사용하게 하세요.
-   항상 `https://`를 사용하세요. 인증서 오류를 피하려고 `http://`로 바꾸거나 인증서 검증을 끄지 마세요.

## 5\. 그래도 해결되지 않나요?

[고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 다음 내용을 함께 보내 주세요: 전체 오류 메시지, 사용 중인 엔드포인트, 서버가 있는 지역, 1단계 curl의 출력 결과.