# 오류 코드

> YesCaptcha API의 모든 오류 코드의 의미와 처리 방법을 요청 형식, 계정 잔액, 동시 작업과 일시 중지, 작업 결과, 사이트 파라미터, 이미지, 프록시, 서버별로 정리했어요. 오류를 반환한 요청은 포인트를 차감하지 않아요.

Source: https://docs.yescaptcha.com/ko/api/errors/ · 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/api/errors/

API 호출이 실패하면 `errorId: 1`이 반환되고, `errorCode`에 오류 코드가, `errorDescription`에 설명 문구가 담겨요. 오류를 반환한 요청은 포인트를 차감하지 않아요. 작업을 만드는 단계에서 난 오류는 차감하지 않고, 작업 생성 후 인식에 실패하거나 시간이 초과된 경우에는 포인트가 자동으로 환불돼요.

> **팁:** 코드에서는 `errorDescription`의 문구가 아니라 `errorCode`로 판단하세요. 설명 문구는 바뀔 수 있어요.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## 처리 원칙

1.  **파라미터 오류**(요청 형식, 키, 작업 유형, 사이트 파라미터, 이미지)는 다시 보내도 결과가 같아요. 먼저 요청을 고치세요.
2.  **인식 실패와 시간 초과**(`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`)는 작업을 새로 만들어서 다시 시도할 수 있어요.
3.  오류가 나면 해당 `taskId`의 **폴링을 멈추세요**. 같은 요청을 그대로 빠르게 반복해서 보내지 마세요.
4.  “자동 일시 중지에 포함”으로 표시된 오류는 같은 `clientKey`에서 1분 안에 100번 발생하면 작업 생성이 5분 동안 일시 중지돼요. “캐시”로 표시된 오류는 횟수에 포함되지 않지만, 캐시 기간에는 같은 요청에 원래 오류가 그대로 반환돼요. 자세한 내용은 [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요.

## 전체 오류 코드

### 요청 형식

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 필수 필드가 없거나(예: `clientKey`, 또는 작업 유형에 필요한 `websiteURL`, `websiteKey`) 요청 본문이 JSON이 아니에요 | 작업 유형 페이지의 파라미터 표를 보고 빠진 필드를 추가하세요. `POST`로 JSON을 보내고 `Content-Type: application/json`을 포함하세요 |
| `ERROR_REQUEST_FORMATS` (자동 일시 중지에 포함) | 요청 본문이 올바른 JSON이 아니에요 | 문자열을 직접 이어 붙이지 말고 JSON 라이브러리로 요청 본문을 만드세요. JSON에는 `//` 주석을 넣을 수 없어요 |
| `ERROR_TASK_ABSENT` (자동 일시 중지에 포함) | `createTask`를 호출할 때 `task` 필드가 없어요 | 작업 파라미터를 `task` 객체에 넣으세요. Python requests에서는 `data=data`가 아니라 `json=data`를 사용하세요 |
| `ERROR_TASK_NOT_SUPPORTED` (자동 일시 중지에 포함) | `task.type`의 철자가 틀렸거나 해당 유형이 종료되었어요 | "작업 유형 및 가격"에서 유형 이름을 복사하세요. 대소문자를 구분해요 |
| `ERROR_PAGE_NOT_FOUND` | 요청한 경로가 존재하지 않아요 | 엔드포인트 주소를 확인하세요. 예: `https://api.yescaptcha.com/createTask`. 메서드 이름은 대소문자를 구분해요 |
| `ERROR_BAD_REQUEST` | 요청을 처리할 수 없어요. 주로 HTTP 메서드가 잘못되었거나(POST 대신 GET 사용) 파라미터 값이 올바르지 않을 때 발생해요 | `POST`로 JSON을 보내고, 파라미터의 타입과 값을 확인하세요 |
| `ERROR_ILLEGAL_PARAMETERS` | 파라미터 값이 올바르지 않아요. Cloudflare 챌린지 페이지에서 흔히 발생해요. `websiteURL`이 `http://` / `https://`로 시작하는 공개 URL이 아니거나, `postData`가 객체가 아니거나, `requiredCookies`가 문자열 배열이 아닌 경우예요(createTask에서 반환되며 포인트는 차감되지 않아요). 또는 프록시를 통해 대상 도메인을 확인할 수 없는 경우예요(getTaskResult에서 반환되며 포인트는 자동으로 환불돼요) | 작업 유형 페이지의 파라미터 표를 보고 값을 수정하세요. 도메인을 확인할 수 없다면 URL 철자와 프록시가 해당 사이트에 접속할 수 있는지 확인하세요 |

### 계정 및 잔액

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (자동 일시 중지에 포함) | `clientKey`가 존재하지 않아요. 복사할 때 문자가 추가되거나 빠졌거나, 대시보드에서 키를 재설정했을 수 있어요 | yescaptcha.com 대시보드에서 키를 다시 복사하세요. 공백이나 줄바꿈이 없어야 해요 |
| `ERROR_KEY_EXPIRED` (자동 일시 중지에 포함) | `clientKey`가 만료되었어요(createTask와 getBalance에서 반환되며, 포인트는 차감되지 않아요). 두 가지 경우가 있어요. 오랫동안 사용하지 않아 계정 보안을 위해 시스템이 만료 시간을 설정한 경우(만료 전에 이메일로 알려 드려요), 또는 이 `clientKey`에 설정한 만료 시간이 지난 경우예요 | yescaptcha.com 대시보드에 로그인하세요. 오랫동안 사용하지 않아 만료된 경우 새 `clientKey`를 생성하세요. 잔액은 새 `clientKey`로 자동 이동해요. 만료 시간을 설정한 경우에는 만료 시간을 변경하거나 다른 `clientKey`를 사용하세요. 그런 다음 프로그램의 `clientKey`를 새 값으로 업데이트하세요 |
| `ERROR_KEY_IP_NOT_ALLOWED` | 이 `clientKey`에는 IP 허용 목록이 설정되어 있는데, 요청을 보낸 IP가 목록에 없어요 (createTask와 getBalance에서 반환돼요. 포인트는 차감되지 않으며, 자동 일시 중지 횟수에도 포함되지 않아요) | yescaptcha.com 대시보드에 로그인해서 요청을 보내는 기기의 공인 IP를 이 `clientKey`의 허용 목록에 추가하거나, 다른 `clientKey`를 사용하세요. 여러 기기에서 API를 호출한다면 각 기기의 공인 IP를 모두 추가해야 해요 (여기서 말하는 IP는 YesCaptcha API를 호출하는 IP이며, 작업 파라미터의 프록시와는 관계없어요) |
| `ERROR_KEY_QUOTA_EXCEEDED` | 이 `clientKey`에는 사용 한도가 설정되어 있는데, 현재 기간에 남은 한도가 이번 작업의 포인트 차감액보다 적어요 (createTask에서 반환돼요. 포인트는 차감되지 않으며, 자동 일시 중지 횟수에도 포함되지 않아요). 한도는 실제로 차감된 포인트를 기준으로 계산하며, 인식 실패나 시간 초과로 환불된 포인트는 한도에도 다시 반영돼요 | yescaptcha.com 대시보드에 로그인해서 이 `clientKey`의 한도를 늘리거나, 다음 기간까지 기다리거나(베이징 시간 기준으로 매일, 매주 월요일 또는 매월 1일에 초기화돼요. 일회성 한도는 초기화되지 않아요), 다른 `clientKey`를 사용하세요. `getBalance`로 이 `clientKey`의 남은 한도(`keyQuotaRemaining`)를 확인할 수 있어요 |
| `ERROR_ZERO_BALANCE` | 잔액이 부족해요. 작업을 만들려면 잔액이 10포인트보다 많아야 해요 | 충전한 뒤 다시 시도하세요. `getBalance`로 잔액을 확인할 수 있어요 |

### 동시 작업 및 일시 중지

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (경우에 따라 자동 일시 중지에 포함) | 이 계정에서 이 유형의 작업이 동시에 너무 많이 처리 중이에요. 응답의 `limit`은 현재 한도예요. 이 요청은 처리되지 않았고 포인트도 차감되지 않았어요 | 이미 보낸 요청이 반환될 때까지 기다린 뒤 새 요청을 보내거나, 1~2초 기다렸다가 다시 시도하세요. 프로그램에서 동시에 결과를 기다리는 요청 수를 제한하세요 |
| `ERROR_IP_BLOCKED_5MIN` | 이 `clientKey`에서 짧은 시간에 오류가 너무 많이 발생해 작업 생성이 자동으로 일시 중지되었어요. 응답의 `retryAfter`는 남은 시간(초)이고 `blockReason`은 일시 중지를 일으킨 오류 코드예요 | `blockReason`에 따라 요청을 수정하고 `retryAfter`초 동안 기다리세요. 일시 중지 중에 요청을 보내도 시간이 늘어나지 않아요 |
| `ERROR_NO_SLOT_AVAILABLE` | 인식 서비스가 일시적으로 과부하 상태예요. `createTask`에서 반환된 경우 포인트가 차감되지 않아요. 대기열에서 너무 오래 기다린 작업은 `getTaskResult`에서도 이 오류가 반환되며, 포인트가 자동으로 환불돼요 | 몇 초 기다린 뒤 작업을 다시 생성하세요 |

### 작업 및 결과

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (자동 일시 중지에 포함) | `taskId`가 존재하지 않거나, 만료되었거나(결과는 약 10분간 보관돼요), 다른 `clientKey`로 생성되었거나, 다른 엔드포인트에서 생성되었어요 | 이 작업의 폴링을 중단하세요. 작업을 생성한 것과 같은 엔드포인트와 같은 `clientKey`로 조회하세요 |
| `ERROR_TASK_TIMEOUT` | 작업이 제한 시간(보통 110초) 안에 완료되지 않았어요. 포인트는 자동으로 환불됐어요 | 작업을 새로 생성하세요. 계속 시간 초과가 발생하면 같은 캡차에 대한 다른 작업 유형을 사용해 보세요 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 이번에는 캡차를 인식하지 못했어요. 포인트는 환불됐어요. 자동 일시 중지 횟수에는 포함되지 않아요 | 작업을 새로 생성하세요. 계속 실패하면 `websiteURL`, `websiteKey` 등의 파라미터를 확인하거나 같은 캡차에 대한 다른 작업 유형을 사용해 보세요 |
| `ERROR_SETTLEMENT_FAILED` (자동 일시 중지에 포함) | 정산 시점에 잔액이 부족해서 결과가 반환되지 않았어요 | 충전한 뒤 작업을 새로 생성하세요 |
| `ERROR_NO_SUCH_CAPCHA_ID` | 작업이 더 이상 유효하지 않아요 | 이 작업의 폴링을 중단하고 새로 생성하세요 |
| `ERROR_RECAPTCHA_TIMEOUT` | 캡차 인식 시간이 초과되었어요. 포인트는 환불됐어요 | 작업을 새로 생성하세요 |

### 대상 웹사이트 파라미터

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (캐시됨, 일시 중지에 포함되지 않음) | `websiteKey`가 유효하지 않아요 | 페이지에서 sitekey를 다시 찾으세요(파라미터 찾기 가이드 참고). 동일한 요청은 캐시 기간 동안 이 오류를 바로 반환하며, 응답에 `cached: true`가 포함돼요 |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (캐시됨, 일시 중지에 포함되지 않음) | `websiteURL`의 도메인이 `websiteKey`와 일치하지 않아요 | `websiteURL`에는 캡차가 표시되는 페이지의 주소를 입력하세요 |
| `ERROR_INVALID_KEY_TYPE` (캐시됨, 일시 중지에 포함되지 않음) | sitekey가 다른 종류의 캡차에 속해요. 예를 들어 v3 키를 v2 작업 유형에 사용한 경우예요 | 먼저 캡차 유형을 확인한 뒤("캡차 유형 판별" 참고) 알맞은 작업 유형을 선택하세요. 보이지 않는 v2는 `isInvisible`을 설정하세요 |
| `ERROR_DOMAIN_NOT_ALLOWED` (캐시됨, 일시 중지에 포함되지 않음) | 이 사이트는 지원되지 않아요 | 같은 캡차에 대한 다른 작업 유형을 사용해 보거나 고객 지원에 문의하세요 |
| `ERROR_HIGH_DEMAND_DOMAIN` (자동 일시 중지에 포함) | 이 사이트는 지원되지 않아요 | 이 사이트의 작업 전송을 중단하고 고객 지원에 문의하세요 |
| `ERROR_FAILED_LOADING_WIDGET` | 입력한 파라미터로 캡차를 불러올 수 없어요 | `websiteURL`과 `websiteKey`를 확인하세요. 자체 프록시를 사용하는 작업 유형은 프록시가 대상 사이트에 접속할 수 있는지 확인하세요 |

### 이미지

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (자동 일시 중지에 포함) | 이미지가 비어 있거나 너무 작아요 | Base64 데이터가 완전한지, `data:image/...;base64,` 접두사가 없는지 확인하세요 |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (자동 일시 중지에 포함) | 이미지가 너무 커요 | 이미지를 압축하거나 크기를 줄이세요. 전체 요청 본문은 6 MB를 넘을 수 없어요 |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (자동 일시 중지에 포함) | 이미지 형식이 지원되지 않거나, 이 작업 유형에서 처리할 수 없는 이미지예요. 한 번만 발생해도 키가 30분 동안 일시 중지돼요 | JPG 또는 PNG를 사용하고 이미지가 작업 유형과 맞는지 확인하세요. 예를 들어 reCAPTCHA 이미지 인식은 100x100, 300x300 또는 450x450 크기가 필요해요 |
| `ERROR_ILLEGAL_IMAGE` (자동 일시 중지에 포함) | 이미지 크기가 이 작업 유형의 요구 사항에 맞지 않아요 | 작업 유형 페이지의 설명에 따라 이미지 크기를 조정하세요 |
| `ERROR_PARSE_IMAGE_FAIL` | 이미지를 디코딩할 수 없어요. Base64가 잘렸거나 접두사가 붙어 있는 경우가 많아요 | Base64 인코딩을 확인하고 `data:` 접두사와 줄바꿈을 제거하세요 |
| `ERROR_UNKNOWN_QUESTION` | `question`이 잘못되었거나, 이 질문이 아직 지원되지 않아요 | 작업 유형 페이지의 질문 목록과 대조해 확인하세요. 지원되지 않는 질문은 고객 지원에 문의하세요. 새로운 질문은 보통 영업일 기준 3일 이내에 지원돼요 |
| `ERROR_UNKNOW_450x450_QUESTION` | 이 질문은 아직 4x4(450x450) 이미지를 지원하지 않아요 | 페이지에서 챌린지를 새로 고쳐 다른 질문을 받으세요 |

### 프록시

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | 프록시가 연결을 거부했어요 | 프록시 주소, 포트, 프로토콜을 확인하고 외부 연결을 허용하는지 확인하세요(127.0.0.1 같은 로컬 주소는 사용할 수 없어요) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | 프록시 연결 시간이 초과되었어요 | 더 안정적인 프록시를 사용하세요 |
| `ERROR_PROXY_READ_TIMEOUT` | 프록시를 통한 데이터 읽기 시간이 초과되었어요 | 더 빠른 프록시를 사용하세요 |
| `ERROR_PROXY_BANNED` | 프록시를 사용할 수 없거나, 프록시 IP가 대상 사이트에서 차단되었어요 | 다른 프록시를 사용하세요 |
| `ERROR_PROXY_INCORRECT` | 프록시 파라미터 형식이 올바르지 않아요 | `proxyType`, `proxyAddress`, `proxyPort`(또는 `proxy` 문자열)의 형식을 확인하세요 |
| `ERROR_PROXY_TRANSPARENT` | 프록시가 투명 프록시라서 실제 IP가 노출돼요 | 익명(엘리트) 프록시로 바꾸세요 |
| `ERROR_PROXY_NOT_AUTHORISED` | 프록시 사용자 이름 또는 비밀번호가 올바르지 않아요 | `proxyLogin`과 `proxyPassword`(또는 `proxy` 문자열에 포함된 인증 정보)를 확인하세요 |
| `ERROR_PROXY_TLS_ERROR` | 프록시와의 TLS 핸드셰이크에 실패했어요. `proxyType`이 잘못된 경우가 많아요(예: http 프록시에 https를 설정한 경우) | 프록시 프로토콜을 확인하세요 |
| `ERROR_PROXY_CONNECTION_FAILED` | 프록시 서버에 연결할 수 없어요 | 프록시 주소와 포트를 확인하고 프록시가 정상 작동하는지 확인하세요 |

### 서버

| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | 서비스를 일시적으로 사용할 수 없어요(코드 철자는 `UNAVALIABLE`이에요) | 잠시 후 다시 시도하세요. 계속 발생하면 고객 지원에 문의하세요 |
| `ERROR_INTERNAL_SERVER_ERROR` | 서버 내부 오류가 발생했어요 | 잠시 후 다시 시도하세요. 계속 발생하면 `taskId`와 함께 고객 지원에 문의하세요 |
| `ERROR_UNKNOWN` | 분류되지 않은 오류예요 | 잠시 후 다시 시도하세요. 계속 발생하면 `taskId`와 함께 고객 지원에 문의하세요 |

## 추가 필드

일부 오류의 응답에는 추가 필드가 포함돼요.

| 필드 | 나타나는 곳 | 설명 |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, 캐시된 오류 | 더 기다려야 하는 시간(초) |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | 일시 중지를 일으킨 오류 코드 |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | 일시 중지를 일으킨 요청의 유형, URL, sitekey. 원인을 찾을 때 활용하세요 |
| `cached` | 캐시된 오류 | `true`이면 캐시된 결과이고 실제로 인식하지 않았다는 뜻이에요 |
| `badRequest` | 캐시된 오류 | 캐시에 걸린 파라미터 |
| `limit` | `ERROR_THREADS_MAXIMUM` | 현재 동시 작업 수 상한 |

`errorDescription`의 언어 규칙은 [요청과 응답](https://docs.yescaptcha.com/ko/api/overview.md)을 참고하세요.