Tham chiếu API

Giới hạn đồng thời và tự động tạm dừng

Trang này được dịch máy từ bản tiếng Trung và có thể có sai sót. Nội dung theo bản tiếng Trung.

Để giữ tốc độ nhận dạng cho mọi người dùng, YesCaptcha có ba quy tắc bảo vệ: giới hạn số tác vụ đang xử lý cùng lúc theo từng tài khoản (giới hạn đồng thời); clientKey tạo quá nhiều lỗi trong thời gian ngắn sẽ bị tạm dừng vài phút (tự động tạm dừng); tham số đã bị xác định là không hợp lệ sẽ được trả về đúng lỗi ban đầu trong một khoảng thời gian (bộ nhớ đệm tham số không hợp lệ). Cả ba trường hợp đều không trừ điểm.

Giới hạn đồng thời

Chúng tôi giới hạn số tác vụ đang xử lý cùng một thời điểm theo từng tài khoản và từng loại tác vụ. Đây là giới hạn số lượng đồng thời, không phải số yêu cầu mỗi phút.

Một tác vụ được tính là “đang xử lý” từ lúc gọi createTask đến khi lệnh gọi đó trả về. Các loại nhận dạng hình ảnh trả kết quả ngay trong createTask, nên số đồng thời ≈ số tác vụ gửi mỗi giây × thời gian xử lý mỗi tác vụ. Ví dụ mỗi tác vụ mất 0.5 giây, mỗi giây gửi 40 tác vụ thì số đồng thời khoảng 20.
Các yêu cầu của cùng một tài khoản được tính gộp; mỗi loại tác vụ được tính riêng.
Yêu cầu vượt hạn mức sẽ trả về ERROR_THREADS_MAXIMUM ngay lập tức, trường limit trong phản hồi là giới hạn hiện tại của bạn. Không trừ điểm và không tính vào tự động tạm dừng.
Khi máy chủ nhận dạng quá tải, tài khoản chiếm nhiều thời gian nhận dạng nhất sẽ bị giảm một nửa giới hạn của loại tác vụ đó trong thời gian tạm thời, tự động khôi phục sau 10 phút. Đây chỉ là giảm tốc độ, không tạm dừng tài khoản.
Nếu cần hạn mức cao hơn, hãy liên hệ hỗ trợ. Sau khi chốt hạn mức mặc định của từng loại, chúng tôi sẽ công bố trên trang này và trong nhật ký cập nhật dịch vụ.

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

(Con số trong ví dụ chỉ mang tính minh họa.)

Cách làm khuyến nghị

Trong chương trình, hãy giới hạn “số yêu cầu đang chờ kết quả cùng lúc”, ví dụ dùng semaphore hoặc thread pool có kích thước cố định, thay vì chỉ kiểm soát số yêu cầu gửi mỗi giây.
Sau khi nhận ERROR_THREADS_MAXIMUM, hãy đợi các yêu cầu đã gửi trả về rồi mới gửi yêu cầu mới, hoặc đợi 1 đến 2 giây rồi thử lại. Không thử lại liên tục trong vòng lặp.
Với tác vụ hàng loạt, hãy gửi đều đặn, đừng gửi hàng nghìn tác vụ cùng một lúc.

Ví dụ 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

Tự động tạm dừng

Khi cùng một clientKey tạo ra nhiều yêu cầu lỗi trong thời gian ngắn, việc tạo tác vụ sẽ bị tự động tạm dừng:

Điều kiện kích hoạt	Thời gian tạm dừng
Trong cùng một phút theo đồng hồ, các lỗi liệt kê bên dưới cộng dồn đạt 100 lần	5 phút
`ERROR_IMAGE_TYPE_NOT_SUPPORTED` xuất hiện 1 lần	30 phút
Trong cùng một phút theo đồng hồ, trúng “bộ nhớ đệm tham số không hợp lệ” 1000 lần	5 phút

Các lỗi được tính vào tạm dừng:

ERROR_THREADS_MAXIMUM do tài khoản vượt giới hạn đồng thời (có trường limit) không được tính; cùng mã lỗi này khi dịch vụ nhận dạng đang bận (không có limit) thì được tính. Nhận dạng thất bại (ERROR_CAPTCHA_UNSOLVABLE), số dư không đủ (ERROR_ZERO_BALANCE), thiếu trường (ERROR_REQUIRED_FIELDS), câu hỏi không được hỗ trợ (ERROR_UNKNOWN_QUESTION) và các lỗi tương tự không được tính.

Trong thời gian tạm dừng:

Chỉ ảnh hưởng đến createTask và getBalance, hai lệnh này trả về ERROR_IP_BLOCKED_5MIN. getTaskResult không bị ảnh hưởng, các tác vụ đã tạo trước khi tạm dừng vẫn tra cứu kết quả bình thường.
Phản hồi có retryAfter (số giây còn lại), blockReason (mã lỗi gây ra tạm dừng) và blockDetail (loại, URL, sitekey của các yêu cầu đó). Hãy dựa vào các trường này để sửa chương trình.
Tiếp tục gửi yêu cầu không làm kéo dài thời gian tạm dừng; hết hạn sẽ tự động khôi phục, không cần liên hệ hỗ trợ.
Trong bảng điều khiển tại yescaptcha.com, bạn có thể xem lịch sử tạm dừng trong 24 giờ gần nhất.

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

Bộ nhớ đệm tham số không hợp lệ

Một số lỗi do chính tham số của yêu cầu quyết định, gửi lại với cùng tham số thì kết quả cũng không đổi:

Các lỗi này không được tính vào tự động tạm dừng mà được lưu đệm trên toàn hệ thống: lưu 2 phút sau lần xác định đầu tiên; nếu được xác nhận lại trong vòng 1 giờ thì lưu 10 phút. Trong thời gian lưu đệm, các yêu cầu giống nhau (cùng loại tác vụ và websiteKey, hoặc cùng tên miền trang web) sẽ trả về ngay lỗi ban đầu, không trừ điểm, phản hồi có "cached": true, retryAfter (số giây còn lại của bộ nhớ đệm) và badRequest (tham số bị trúng). Sửa websiteKey hoặc đổi loại tác vụ sẽ có hiệu lực ngay.

Khác biệt giữa giới hạn đồng thời và tự động tạm dừng

	Giới hạn đồng thời	Tự động tạm dừng
Nguyên nhân	Có quá nhiều tác vụ đang xử lý cùng lúc	Có quá nhiều yêu cầu lỗi trong thời gian ngắn
Biểu hiện	Chỉ từ chối phần yêu cầu vượt mức, `ERROR_THREADS_MAXIMUM`	`clientKey` này bị tạm dừng tạo tác vụ, `ERROR_IP_BLOCKED_5MIN`
Khôi phục	Có yêu cầu xử lý xong là gửi được yêu cầu mới; giới hạn bị giảm một nửa sẽ khôi phục sau 10 phút	Hết hạn tự động khôi phục
Trừ điểm	Không trừ	Không trừ