# 동시 작업 수 제한과 자동 일시 중지

> YesCaptcha의 동시 작업 수 제한(ERROR_THREADS_MAXIMUM, 포인트 차감 없음, 일시 중지에 포함되지 않음), 오류가 너무 많을 때의 자동 일시 중지(1분에 100회 발생하면 5분간 일시 중지, ERROR_IP_BLOCKED_5MIN), 잘못된 파라미터 캐시(cached)를 설명해요.

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

모든 사용자의 캡차 인식 속도를 유지하기 위해 YesCaptcha에는 세 가지 보호 규칙이 있어요. 계정별로 **동시에 처리 중인 작업 수**를 제한하고(동시 작업 수 제한), 같은 `clientKey`에서 짧은 시간 안에 **오류가 너무 많이 발생하면 몇 분간 일시 중지**하고(자동 일시 중지), **이미 잘못된 것으로 판정된 파라미터**는 일정 시간 동안 원래 오류를 그대로 반환해요(잘못된 파라미터 캐시). 이 세 경우 모두 포인트가 차감되지 않아요.

## 동시 작업 수 제한

계정별, 작업 유형별로 같은 시각에 처리 중인 작업 수를 제한해요. 제한하는 것은 동시 작업 수이며, 분당 요청 수가 아니에요.

-   `createTask`를 호출한 시점부터 그 호출이 반환될 때까지 작업은 “처리 중”으로 계산돼요. 이미지 인식 유형은 `createTask`에서 바로 결과를 반환하므로 **동시 작업 수 ≈ 초당 전송한 작업 수 × 작업 하나당 소요 시간**이에요. 예를 들어 작업당 0.5초, 초당 40개를 보내면 동시 작업 수는 약 20이에요.
-   같은 계정의 요청은 합산해서 계산해요. 작업 유형은 각각 따로 계산해요.
-   한도를 초과한 요청은 즉시 `ERROR_THREADS_MAXIMUM`을 반환하고, 응답의 `limit`은 현재 상한이에요. **포인트는 차감되지 않으며 자동 일시 중지에도 포함되지 않아요.**
-   인식 서버가 바쁠 때는 인식 시간을 가장 많이 사용한 계정의 해당 작업 유형 상한이 **일시적으로 절반으로 줄었다가 10분 후 자동으로 복구돼요.** 속도만 제한할 뿐 계정을 일시 중지하지는 않아요.
-   더 높은 한도가 필요하면 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의하세요. 유형별 기본 한도가 확정되면 이 페이지와 [서비스 업데이트 기록](https://docs.yescaptcha.com/ko/changelog.md)에 공개할 예정이에요.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_THREADS_MAXIMUM",
  "errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
  "limit": 30
}
```

(예시의 숫자는 참고용이에요.)

### 권장 방법

1.  초당 몇 개를 보낼지만 제어하지 말고, 세마포어(Semaphore)나 고정 크기 스레드 풀 등으로 “결과를 기다리는 동시 요청 수”를 프로그램에서 제한하세요.
2.  `ERROR_THREADS_MAXIMUM`을 받으면 이미 보낸 요청이 반환될 때까지 기다린 후 새 요청을 보내거나, 1~2초 기다렸다가 다시 시도하세요. 즉시 반복해서 재시도하지 마세요.
3.  일괄 작업은 고르게 나눠서 보내고, 수천수만 개의 작업을 한꺼번에 보내지 마세요.

Python(asyncio) 예시예요.

```python
import asyncio
import os

import aiohttp

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15  # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)

async def solve(session, task):
    async with sem:  # at most LIMIT requests in progress at a time
        result = {}
        for attempt in range(5):
            async with session.post(
                "https://api.yescaptcha.com/createTask",
                json={"clientKey": CLIENT_KEY, "task": task},
            ) as resp:
                result = await resp.json()
            if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
                return result
            await asyncio.sleep(1 + attempt)  # over the limit: wait and retry
        return result
```

## 자동 일시 중지

같은 `clientKey`에서 짧은 시간 안에 오류 요청이 대량으로 발생하면 작업 생성이 자동으로 일시 중지돼요.

| 발동 조건 | 일시 중지 시간 |
| --- | --- |
| 같은 1분(자연 분) 안에 아래에 나열된 오류가 누적 100회 발생 | 5분 |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` 1회 발생 | 30분 |
| 같은 1분(자연 분) 안에 “잘못된 파라미터 캐시”에 1,000회 적중 | 5분 |

일시 중지에 포함되는 오류:

-   [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_REQUEST_FORMATS)
-   [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASK_ABSENT)
-   [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
-   [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
-   [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED)
-   [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASKID_INVALID)
-   [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_SETTLEMENT_FAILED)
-   [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
-   [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
-   [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
-   [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
-   [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_ILLEGAL_IMAGE)

계정의 동시 작업 수 초과로 반환되는 `ERROR_THREADS_MAXIMUM`(`limit` 필드 포함)은 포함되지 않아요. 인식 서비스가 바쁠 때 반환되는 같은 이름의 오류(`limit` 없음)는 포함돼요. 인식 실패(`ERROR_CAPTCHA_UNSOLVABLE`), 잔액 부족(`ERROR_ZERO_BALANCE`), 필수 필드 누락(`ERROR_REQUIRED_FIELDS`), 지원하지 않는 질문(`ERROR_UNKNOWN_QUESTION`) 등은 포함되지 않아요.

일시 중지 중에는 다음과 같아요.

-   `createTask`와 `getBalance`에만 영향을 주며 `ERROR_IP_BLOCKED_5MIN`을 반환해요. `getTaskResult`는 영향을 받지 않아서, 일시 중지 전에 만든 작업의 결과는 평소처럼 조회할 수 있어요.
-   응답에 `retryAfter`(남은 시간, 초), `blockReason`(일시 중지를 일으킨 오류 코드), `blockDetail`(해당 요청의 유형, URL, sitekey)이 포함돼요. 이를 보고 프로그램을 수정하세요.
-   요청을 계속 보내도 일시 중지 시간이 늘어나지 않아요. 시간이 지나면 자동으로 복구되므로 고객 지원에 문의할 필요가 없어요.
-   [yescaptcha.com](https://yescaptcha.com/) 대시보드에서 최근 24시간의 일시 중지 기록을 확인할 수 있어요.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_IP_BLOCKED_5MIN",
  "errorDescription": "...",
  "retryAfter": 182,
  "blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```

## 잘못된 파라미터 캐시

일부 오류는 요청 파라미터에 의해 결정되므로, 같은 파라미터로 다시 보내도 결과가 바뀌지 않아요.

-   [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
-   [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
-   [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_INVALID_KEY_TYPE)
-   [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)

이런 오류는 자동 일시 중지에 포함되지 않고, 대신 사이트 전체에서 캐시돼요. 처음 판정된 후 2분간 캐시되고, 1시간 안에 다시 확인되면 10분간 캐시돼요. 캐시 기간 중에 같은 요청(같은 작업 유형과 `websiteKey`, 또는 같은 웹사이트 도메인)을 보내면 원래 오류를 바로 반환하고 포인트는 차감되지 않으며, 응답에 `"cached": true`, `retryAfter`(캐시 남은 시간, 초), `badRequest`(적중한 파라미터)가 포함돼요. `websiteKey`를 바로잡거나 작업 유형을 바꾸면 즉시 적용돼요.

## 동시 작업 수 제한과 자동 일시 중지의 차이

|  | 동시 작업 수 제한 | 자동 일시 중지 |
| --- | --- | --- |
| 원인 | 동시에 처리 중인 작업이 너무 많음 | 짧은 시간 안에 오류 요청이 너무 많음 |
| 증상 | 초과한 요청만 거부, `ERROR_THREADS_MAXIMUM` | 해당 `clientKey`의 작업 생성이 일시 중지, `ERROR_IP_BLOCKED_5MIN` |
| 복구 | 처리가 끝난 요청이 있으면 바로 새 요청을 보낼 수 있음. 일시적으로 절반이 된 상한은 10분 후 복구 | 시간이 지나면 자동 복구 |
| 포인트 차감 | 없음 | 없음 |