API 레퍼런스

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

이 페이지는 중국어 버전을 기계 번역한 것이라 부정확한 내용이 있을 수 있어요. 중국어 버전을 기준으로 해 주세요.

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

동시 작업 수 제한

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

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

{
  "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
}

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

권장 방법

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

Python(asyncio) 예시예요.

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_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 대시보드에서 최근 24시간의 일시 중지 기록을 확인할 수 있어요.

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

잘못된 파라미터 캐시

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

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

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

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