# Cloudflare 챌린지 페이지

> YesCaptcha로 Cloudflare의 "잠시만 기다리세요" 확인 페이지(Cloudflare 챌린지 페이지)를 통과하고 cf_clearance 등 쿠키, User-Agent, 웹페이지 내용을 받아요. CloudFlareTaskS2와 CloudFlareTaskS3의 파라미터, 프록시 요구 사항, 반환 결과, 결과 사용 방법, 자주 발생하는 오류를 설명해요.

Source: https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge/ · Last verified: 2026-10-19

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

Cloudflare 챌린지 페이지는 사이트 전체를 Cloudflare가 가로막고 “잠시만 기다리세요…”, “브라우저를 확인하는 중”을 표시하는 확인 페이지예요. YesCaptcha는 사용자가 제공한 프록시로 페이지를 열어 확인을 통과한 뒤, `cf_clearance` 등 쿠키, 당시 사용한 User-Agent, 요청 헤더, 응답 헤더, 통과 후의 웹페이지 HTML을 반환해요. `CloudFlareTaskS2`는 작업당 25 포인트 (≈ $3.75 / 1k), `CloudFlareTaskS3`는 작업당 20 포인트 (≈ $3.00 / 1k)예요. 두 유형은 파라미터, 반환 결과, 효과가 모두 같고 가격만 달라요. 비동기로 결과를 반환하며, 작업 하나는 보통 6~35초가 걸리고 사이트마다 차이가 커요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.

- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)

## 사용 상황

-   페이지 소스에 `__cf_chl_rt_tk` 또는 `cdn-cgi/challenge-platform`이 있고 제목이 `Just a moment...` / “잠시만 기다리세요”예요. 이 경우가 Cloudflare 챌린지 페이지예요. 확인 페이지에서 “사람인지 확인” 체크박스를 눌러야 하는 경우도 이 페이지에서 다뤄요.
-   폼 안에 Cloudflare 인증 위젯만 삽입되어 있다면 [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)이므로 이 페이지를 쓰지 않아요.
-   requests 같은 라이브러리로 요청하면 403과 “Just a moment…“가 반환되지만 브라우저에서는 바로 열려요. 대부분 TLS 핑거프린트 때문에 차단된 거예요. 브라우저의 TLS 핑거프린트를 흉내 내는 라이브러리(예: curl\_cffi)로 바꾸면 요청할 수 있고, 챌린지 통과는 필요 없어요.

## 유형과 가격

| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `CloudFlareTaskS2` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | 자체 프록시 |
| `CloudFlareTaskS3` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | 자체 프록시 |

미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.

## 요청 파라미터

| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 챌린지에 막힌 페이지의 전체 URL이에요. `http://` 또는 `https://`로 시작하는 공개 URL이어야 해요. 사설 IP 주소와 `localhost` 같은 로컬 또는 내부 호스트 이름은 거부돼요 |
| `proxy` | string | 예 | 문자열 하나로 된 프록시예요: `http://user:pass@proxy.example.com:8080`(HTTP 프록시, 인증 정보는 선택) 또는 `socks5://proxy.example.com:1080`(인증 정보 없음). `https://` 프록시와 인증 정보가 있는 SOCKS5는 지원하지 않고, 로컬 또는 사설 주소는 거부돼요. 대상 페이지에 대한 모든 요청이 이 프록시를 통해 전송돼요 |
| `userAgent` | string | 아니요 | 보통은 생략하세요. Linux 데스크톱 Chrome의 User-Agent만 사용되고, 그 외(Windows, macOS, 모바일, 다른 브라우저)는 무시돼요. 이후 요청에는 항상 결과의 `user_agent`를 사용하세요 |
| `waitLoad` | boolean | 아니요 | 기본값은 false예요. true로 설정하면 검증을 통과한 뒤 페이지의 네트워크 활동이 잠잠해질 때까지 기다린 다음 반환해요. 그래서 `content`에 동적으로 불러온 내용이 더 많이 포함되지만 몇 초 더 걸려요 |
| `requiredCookies` | array | 아니요 | 반드시 가져와야 하는 쿠키 이름 목록이에요. 문자열 배열로 전달하세요. 예: `["cf_clearance"]`. 설정하면 모두 가져왔을 때만 성공해요. 하나라도 가져오지 못하면 `ERROR_CAPTCHA_UNSOLVABLE`을 반환하고 포인트가 환불돼요. 생략하면 `cf_clearance`를 가져오려고 시도하지만, 다른 쿠키만 가져와도 성공으로 처리되어 포인트가 차감돼요. `cf_clearance`가 필요하면 반드시 명시적으로 전달하세요 |
| `blockImage` | boolean | 아니요 | true로 설정하면 대상 페이지의 이미지를 불러오지 않아요(Cloudflare 검증 자체에 필요한 이미지는 제외). 프록시 트래픽을 절약할 수 있어요 |
| `postData` | object | 아니요 | 설정하면 일반 HTML 폼 POST처럼 `websiteURL`로 제출돼요(`application/x-www-form-urlencoded`). 각 키는 폼 필드이고 값은 문자열로 전송돼요. 예: `{"name": "hi"}`. 반드시 객체여야 해요 |

### 프록시 요구 사항

`proxy`는 필수예요. 대상 웹페이지를 여는 모든 요청이 이 프록시를 거쳐요. `cf_clearance`는 출구 IP에 묶여 있으므로, 이후 대상 사이트에 접속할 때도 같은 프록시를 써야 해요.

| 형식 | 지원 여부 |
| --- | --- |
| `http://user:pass@proxy.example.com:8080` | 지원: http 프록시, 계정과 비밀번호 포함 |
| `http://proxy.example.com:8080` | 지원: http 프록시, 계정과 비밀번호 없음 |
| `socks5://proxy.example.com:1080` | 지원: socks5 프록시, 계정과 비밀번호 없음. `socks5h://`는 `socks5://`로 처리해요 |
| `socks5://user:pass@proxy.example.com:1080` | 지원 안 함, `ERROR_PROXY_INCORRECT` 반환. 계정과 비밀번호가 필요하면 http 프록시를 쓰세요 |
| `https://proxy.example.com:443` 등 다른 프로토콜, 또는 포트 누락 | 지원 안 함, `ERROR_PROXY_INCORRECT` 반환 |
| `127.0.0.1`, `192.168.x.x`, `10.x.x.x` 같은 로컬, 내부망, 예약 주소 또는 이런 주소로 확인되는 도메인 | 거부, `ERROR_PROXY_BANNED` 반환 |

> **작업을 만들 때 바로 검사해요:** URL이나 프록시가 규칙에 맞지 않으면 `createTask`가 바로 오류를 반환하고 포인트는 차감되지 않아요. 같은 프록시가 짧은 시간에 여러 번 연결되지 않으면, 이후 한동안은 그 프록시로 작업을 만들 때도 바로 `ERROR_PROXY_BANNED`가 반환돼요. 프록시를 바꾸거나 잠시 후 다시 시도하세요.

### User-Agent

보통은 `userAgent`를 보내지 않아요. YesCaptcha는 Linux 데스크톱 버전 Chrome으로 확인을 통과해요. 같은 Linux 데스크톱 버전 Chrome의 User-Agent만 적용되고, 그 밖의 것(Windows, macOS, 모바일, 다른 브라우저)은 무시해요. 실측 결과 브라우저의 실제 환경과 User-Agent가 맞지 않으면 Cloudflare 확인을 통과하지 못했어요. 이후 요청에는 항상 결과의 `user_agent`를 쓰세요.

## 요청 예시

POST https://api.yescaptcha.com/createTask

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "CloudFlareTaskS3",
    "websiteURL": "https://example.com/",
    "proxy": "http://user:pass@proxy.example.com:8080",
    "requiredCookies": ["cf_clearance"]
  }
}
```

-   `CloudFlareTaskS2`를 쓰려면 `type`만 바꾸고 나머지는 그대로 두세요.
-   `requiredCookies`에 `["cf_clearance"]`를 보내면 `cf_clearance`를 받지 못했을 때 작업이 실패하고 포인트가 환불돼요. 보내지 않으면 `cf_clearance` 없이 다른 쿠키만 받아도 성공으로 처리되어 포인트가 차감돼요.
-   폼을 제출해야 하면 `postData`를 추가하세요. 예: `{"name": "hi"}`. `websiteURL`로 POST 폼 방식으로 제출돼요.

작업을 만든 뒤에는 5초마다 `getTaskResult`를 호출하세요. 흐름은 다른 비동기 작업과 같아요. [getTaskResult](https://docs.yescaptcha.com/ko/api/get-task-result.md)를 참고하세요.

## 반환 결과

```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "cookies": {
      "cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
    },
    "request_headers": {
      "accept-language": "en-US,en;q=0.9",
      "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
    },
    "headers": {
      "content-type": "text/html; charset=UTF-8",
      "server": "cloudflare"
    },
    "content": "<!DOCTYPE html>..."
  }
}
```

위의 쿠키 값과 요청 헤더는 예시예요. 실제 값은 반환된 결과를 따르세요.

| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `cookies` | object | 검증을 통과한 뒤 브라우저에 있는 모든 쿠키예요(이름-값 객체). 보통 `cf_clearance`가 포함돼요. `requiredCookies`를 보냈다면 그 쿠키가 모두 포함돼요. 반환된 `user_agent`, 작업을 만들 때 사용한 프록시와 함께 사용하세요 |
| `user_agent` | string | 검증을 통과할 때 브라우저가 실제로 사용한 User-Agent예요(Linux 데스크톱 Chrome). `cf_clearance`가 이 값에 연결되어 있으므로 이후 모든 요청에 이 값을 사용해야 해요 |
| `request_headers` | object | 브라우저가 대상 웹페이지를 마지막으로 요청할 때 보낸 요청 헤더예요. 이후 요청에도 같은 헤더를 사용하는 것을 권장해요 |
| `headers` | object | 검증을 통과한 뒤 받은 대상 웹페이지의 응답 헤더예요 |
| `content` | string | 검증을 통과한 뒤 받은 대상 웹페이지의 HTML 소스예요 |

## 결과 사용 방법

1.  이후 요청에는 반환된 `cookies`, 반환된 `user_agent`, 작업을 만들 때 쓴 같은 프록시를 **모두 함께** 쓰세요. `cf_clearance`는 User-Agent, 출구 IP에 묶여 있어서 셋 중 하나라도 다르면 챌린지 페이지가 다시 나타나요.
2.  요청 헤더도 가능하면 `request_headers`대로 보내고, 브라우저와 같은 TLS 핑거프린트를 쓰세요(예: curl\_cffi의 `impersonate` 파라미터).
3.  `cf_clearance`에는 유효 기간이 있어요(대상 사이트가 설정하며, 길면 1시간까지 가는 경우도 있어요). 유효 기간 안에는 챌린지를 다시 통과할 필요가 없어요. 다만 요청 빈도가 너무 높으면 Cloudflare가 IP를 차단할 수 있어요.
4.  웹페이지 내용만 필요하면 `content`를 그대로 쓰면 돼요. 다시 요청할 필요가 없어요.

## 자주 발생하는 오류

작업을 만들 때 반환된 오류는 포인트가 차감되지 않아요. 작업을 만든 뒤 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요. 인터페이스는 오류 코드와 일반적인 설명만 반환하므로, 구체적인 원인은 아래 표에서 확인하세요.

| 오류 코드 | 반환되는 경우 | 해결 방법 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 작업 생성 시: `websiteURL` 또는 `proxy`가 없음 | 필수 필드 두 개를 모두 채우세요 |
| `ERROR_ILLEGAL_PARAMETERS` | 작업 생성 시: `websiteURL`이 `http://` / `https://`로 시작하는 공개 URL이 아님, `postData`가 객체가 아님, `requiredCookies`가 문자열 배열이 아님. 결과 조회 시: 프록시를 통해 대상 URL의 도메인을 확인할 수 없음 | 파라미터를 고치세요. URL 철자와 프록시가 해당 사이트에 접속할 수 있는지 확인하세요 |
| `ERROR_PROXY_INCORRECT` | 작업 생성 시: 프록시 형식이 올바르지 않거나 포트가 없음, `https://` 프록시 또는 계정과 비밀번호가 있는 socks5를 사용함 | 위 “프록시 요구 사항”의 형식으로 고치세요. 계정과 비밀번호가 필요하면 http 프록시를 쓰세요 |
| `ERROR_PROXY_BANNED` | 작업 생성 시: 프록시가 로컬, 내부망 또는 예약 주소이거나, 이 프록시가 짧은 시간에 여러 번 연결되지 않음. 결과 조회 시: 대상 사이트의 Cloudflare가 이 프록시의 IP를 바로 차단함(“Sorry, you have been blocked”, “Access denied” 페이지) | 프록시를 바꾸세요. IP 품질이 좋을수록 통과하기 쉬워요 |
| `ERROR_PROXY_CONNECT_REFUSED` | 프록시에 연결할 수 없거나(연결 거부, 프록시 도메인을 확인할 수 없음), 프록시를 통해 웹페이지를 여는 중 연결이 거부되거나 재설정됨 | 프록시 주소와 포트를 확인하고, 프록시가 온라인이며 외부 접속을 허용하는지 확인하세요. 계속 실패하면 프록시를 바꾸세요 |
| `ERROR_PROXY_CONNECT_TIMEOUT` | 프록시에 연결하거나 프록시를 통해 웹페이지를 여는 중 시간이 초과됨 | 더 빠르고 안정적인 프록시로 바꾸세요 |
| `ERROR_PROXY_NOT_AUTHORISED` | 프록시의 계정 또는 비밀번호가 올바르지 않음 | `proxy`의 계정과 비밀번호를 확인하세요. 특수 문자는 URL 인코딩해야 해요 |
| `ERROR_PROXY_TLS_ERROR` | 프록시를 통해 웹페이지를 여는 중 TLS 핸드셰이크 오류가 발생함 | 프록시 주소, 포트, 프로토콜이 맞는지 확인하세요. 계속 실패하면 프록시를 바꾸세요 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 제한 시간 안에 확인을 통과하지 못했거나, 통과 후에도 챌린지 페이지에 머물러 있거나, `requiredCookies`에 지정한 쿠키를 받지 못함 | 먼저 프록시를 바꿔서 다시 시도하세요. 일부 사이트는 고객 지원에 문의하세요 |
| `ERROR_NO_SLOT_AVAILABLE` | 작업 생성 시: 대기열이 가득 참. 결과 조회 시: 대기 시간이 너무 길어 시작하지 못했고 포인트가 환불됨 | 몇 초 기다린 뒤 작업을 다시 만드세요 |
| `ERROR_TASK_TIMEOUT` | 작업이 제한 시간 안에 완료되지 않음 | 작업을 다시 만드세요. 시간 초과가 계속되면 대개 프록시가 너무 느린 거예요 |

전체 오류 코드는 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.

## 관련 문서

-   [캡차 유형 판별](https://docs.yescaptcha.com/ko/guides/identify-captcha.md): Cloudflare 챌린지 페이지와 Turnstile의 차이
-   [Cloudflare Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)