Mã lỗi

Khi giao diện gặp lỗi, API trả về errorId: 1; errorCode là mã lỗi, errorDescription là mô tả bằng văn bản. Yêu cầu trả về lỗi không bị trừ điểm: lỗi xảy ra ngay lúc tạo tác vụ thì không trừ, còn tác vụ nhận dạng thất bại hoặc hết thời gian sau khi đã tạo sẽ tự động hoàn điểm.

Mẹo

Trong chương trình, hãy xử lý theo errorCode, đừng dựa vào nội dung của errorDescription, vì mô tả văn bản có thể thay đổi.

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

Nguyên tắc xử lý

1. Lỗi tham số (định dạng yêu cầu, clientKey, loại tác vụ, tham số trang web, hình ảnh): gửi lại vẫn không đổi kết quả, cần sửa yêu cầu trước.
2. Nhận dạng thất bại và hết thời gian (ERROR_CAPTCHA_UNSOLVABLE, ERROR_TASK_TIMEOUT): có thể tạo lại tác vụ.
3. Sau khi gặp lỗi, hãy dừng polling taskId đó, đừng gửi lại nguyên yêu cầu với tần suất cao.
4. Với lỗi được đánh dấu “Tính vào tự động tạm dừng”: nếu cùng một clientKey gặp 100 lỗi như vậy trong một phút, việc tạo tác vụ sẽ bị tạm dừng 5 phút. Lỗi được đánh dấu “Cache” thì không được tính, nhưng trong thời gian cache, cùng một yêu cầu sẽ trả về ngay lỗi ban đầu. Xem chi tiết tại Giới hạn đồng thời và tự động tạm dừng.

Tất cả mã lỗi

Định dạng yêu cầu

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_REQUIRED_FIELDS	Thiếu một trường bắt buộc (như clientKey, hoặc websiteURL / websiteKey theo loại tác vụ), hoặc nội dung yêu cầu không phải JSON	Bổ sung các trường còn thiếu được liệt kê trên trang loại tác vụ, và gửi JSON bằng POST kèm Content-Type: application/json
ERROR_REQUEST_FORMATS Tính vào tự động tạm dừng	Nội dung yêu cầu không phải JSON hợp lệ	Tạo nội dung yêu cầu bằng thư viện JSON thay vì ghép chuỗi; JSON không được chứa chú thích //
ERROR_TASK_ABSENT Tính vào tự động tạm dừng	Thiếu trường task trong lệnh gọi createTask	Đặt các tham số của tác vụ vào đối tượng task. Với Python requests hãy dùng json=data, không dùng data=data
ERROR_TASK_NOT_SUPPORTED Tính vào tự động tạm dừng	task.type bị sai chính tả hoặc loại tác vụ này đã ngừng cung cấp	Sao chép tên loại tác vụ từ "Loại tác vụ và bảng giá"; tên phân biệt chữ hoa chữ thường
ERROR_PAGE_NOT_FOUND	Đường dẫn được yêu cầu không tồn tại	Kiểm tra URL endpoint, ví dụ https://api.yescaptcha.com/createTask; tên phương thức phân biệt chữ hoa chữ thường
ERROR_BAD_REQUEST	Không thể xử lý yêu cầu, thường do dùng sai phương thức HTTP (GET thay vì POST) hoặc giá trị tham số không hợp lệ	Gửi JSON bằng POST, và kiểm tra kiểu cũng như giá trị của các tham số
ERROR_ILLEGAL_PARAMETERS	Giá trị tham số không hợp lệ. Thường gặp với trang thử thách Cloudflare: websiteURL không phải URL công khai bắt đầu bằng http:// / https://, postData không phải đối tượng, hoặc requiredCookies không phải mảng chuỗi (do createTask trả về, không trừ điểm); hoặc không phân giải được tên miền đích qua proxy (do getTaskResult trả về, đã tự động hoàn điểm)	Sửa giá trị theo bảng tham số trên trang loại tác vụ. Nếu không phân giải được tên miền, hãy kiểm tra chính tả URL và xem proxy có truy cập được website đó không

Tài khoản và số dư

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_KEY_DOES_NOT_EXIST Tính vào tự động tạm dừng	clientKey không tồn tại: bị thừa hoặc thiếu ký tự khi sao chép, hoặc khóa đã được đặt lại trong bảng điều khiển	Sao chép lại khóa từ bảng điều khiển trên yescaptcha.com, không kèm dấu cách hoặc ký tự xuống dòng
ERROR_KEY_EXPIRED Tính vào tự động tạm dừng	clientKey đã hết hạn (do createTask và getBalance trả về, không trừ điểm). Có hai trường hợp: clientKey không được sử dụng trong thời gian dài nên hệ thống đã đặt thời hạn để bảo vệ tài khoản (sẽ có email nhắc trước khi hết hạn), hoặc thời hạn được đặt cho clientKey này đã qua	Đăng nhập vào bảng điều khiển trên yescaptcha.com. Nếu clientKey hết hạn do lâu không sử dụng, hãy tạo clientKey mới; số dư sẽ tự động chuyển sang clientKey mới. Nếu đã đặt thời hạn, hãy thay đổi thời hạn hoặc dùng clientKey khác. Sau đó cập nhật clientKey mới vào chương trình của bạn
ERROR_KEY_IP_NOT_ALLOWED	clientKey này có danh sách IP được phép (allowlist) và IP gửi yêu cầu không nằm trong danh sách đó (được trả về bởi createTask và getBalance, không trừ điểm, không tính vào tự động tạm dừng)	Đăng nhập vào bảng điều khiển yescaptcha.com và thêm IP công khai của máy đang gửi yêu cầu vào danh sách IP được phép của clientKey này, hoặc dùng clientKey khác. Nếu gọi API từ nhiều máy, hãy thêm IP công khai của từng máy (đây là IP gọi API của YesCaptcha, không phải proxy trong tham số tác vụ)
ERROR_KEY_QUOTA_EXCEEDED	clientKey này có hạn mức chi tiêu và phần còn lại của chu kỳ hiện tại ít hơn số điểm cần trừ cho tác vụ này (được trả về bởi createTask, không trừ điểm, không tính vào tự động tạm dừng). Hạn mức tính theo số điểm thực tế đã trừ; điểm được hoàn lại do tác vụ thất bại hoặc hết thời gian chờ cũng được trả về hạn mức	Đăng nhập vào bảng điều khiển yescaptcha.com và tăng hạn mức của clientKey này, hoặc chờ chu kỳ tiếp theo (đặt lại hằng ngày, vào thứ Hai hằng tuần hoặc ngày 1 hằng tháng, theo giờ Bắc Kinh; hạn mức dùng một lần không được đặt lại), hoặc dùng clientKey khác. getBalance trả về hạn mức còn lại của clientKey này (keyQuotaRemaining)
ERROR_ZERO_BALANCE	Số dư không đủ. Số dư phải lớn hơn 10 điểm mới tạo được tác vụ	Nạp tiền rồi thử lại. Dùng getBalance để kiểm tra số dư

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

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_THREADS_MAXIMUM Một số trường hợp tính vào tự động tạm dừng	Tài khoản có quá nhiều tác vụ loại này đang được xử lý. limit trong phản hồi là giới hạn hiện tại. Yêu cầu không được xử lý và không bị trừ điểm	Chờ các yêu cầu đang xử lý trả về, hoặc chờ 1–2 giây rồi thử lại; hãy giới hạn số yêu cầu cùng chờ kết quả tại một thời điểm
ERROR_IP_BLOCKED_5MIN	clientKey này gây ra quá nhiều lỗi trong thời gian ngắn và đã bị tự động tạm dừng. retryAfter là số giây còn lại và blockReason là mã lỗi gây ra việc tạm dừng	Sửa yêu cầu theo blockReason và chờ retryAfter giây; việc tiếp tục gửi trong thời gian tạm dừng không làm kéo dài thời gian đó
ERROR_NO_SLOT_AVAILABLE	Dịch vụ nhận dạng tạm thời quá tải. Khi createTask trả về lỗi này thì không trừ điểm; tác vụ xếp hàng quá lâu cũng sẽ trả về lỗi này từ getTaskResult, và được hoàn điểm tự động	Chờ vài giây rồi tạo lại tác vụ

Tác vụ và kết quả

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_TASKID_INVALID Tính vào tự động tạm dừng	taskId không tồn tại, đã hết hạn (kết quả được lưu khoảng 10 phút), thuộc về clientKey khác, hoặc được tạo trên endpoint còn lại	Dừng polling tác vụ này. Truy vấn bằng đúng endpoint và clientKey đã dùng để tạo tác vụ
ERROR_TASK_TIMEOUT	Tác vụ không hoàn thành trong thời gian quy định (thường là 110 giây); điểm đã được hoàn tự động	Tạo tác vụ mới; nếu liên tục hết thời gian chờ, hãy thử loại tác vụ khác cho cùng loại captcha
ERROR_CAPTCHA_UNSOLVABLE	Lần này không nhận dạng được captcha; điểm đã được hoàn. Lỗi này không được tính vào tự động tạm dừng	Tạo tác vụ mới. Nếu vẫn liên tục thất bại, hãy kiểm tra websiteURL, websiteKey và các tham số khác, hoặc thử loại tác vụ khác cho cùng loại captcha
ERROR_SETTLEMENT_FAILED Tính vào tự động tạm dừng	Số dư không đủ tại thời điểm quyết toán nên không trả về kết quả	Nạp tiền rồi tạo tác vụ mới
ERROR_NO_SUCH_CAPCHA_ID	Tác vụ không còn hiệu lực	Dừng polling tác vụ này và tạo tác vụ mới
ERROR_RECAPTCHA_TIMEOUT	Nhận dạng captcha bị hết thời gian chờ; điểm đã được hoàn	Tạo tác vụ mới

Tham số website đích

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_RECAPTCHA_INVALID_SITEKEY Dùng bộ nhớ đệm, không tính vào tạm dừng	websiteKey không hợp lệ	Tìm lại sitekey trong trang web (xem các hướng dẫn tìm tham số). Trong thời gian lưu cache, các yêu cầu giống hệt sẽ trả về ngay lỗi này, kèm cached: true
ERROR_RECAPTCHA_INVALID_DOMAIN Dùng bộ nhớ đệm, không tính vào tạm dừng	Tên miền của websiteURL không khớp với websiteKey	Điền websiteURL là địa chỉ trang hiển thị captcha
ERROR_INVALID_KEY_TYPE Dùng bộ nhớ đệm, không tính vào tạm dừng	Sitekey thuộc về loại captcha khác, ví dụ dùng key của v3 cho loại tác vụ v2	Hãy xác định loại captcha trước (xem "Xác định loại captcha") rồi chọn loại tác vụ tương ứng; với v2 ẩn (invisible), hãy truyền isInvisible
ERROR_DOMAIN_NOT_ALLOWED Dùng bộ nhớ đệm, không tính vào tạm dừng	Trang web này hiện chưa được hỗ trợ	Thử loại tác vụ khác cho cùng loại captcha, hoặc liên hệ bộ phận hỗ trợ
ERROR_HIGH_DEMAND_DOMAIN Tính vào tự động tạm dừng	Trang web này hiện chưa được hỗ trợ	Ngừng gửi tác vụ cho trang web này và liên hệ bộ phận hỗ trợ để xác nhận
ERROR_FAILED_LOADING_WIDGET	Không tải được captcha với các tham số đã cung cấp	Kiểm tra websiteURL và websiteKey; với các loại tác vụ dùng proxy riêng, kiểm tra proxy có truy cập được trang web đích hay không

Hình ảnh

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_ZERO_CAPTCHA_FILESIZE Tính vào tự động tạm dừng	Ảnh trống hoặc quá nhỏ	Kiểm tra dữ liệu Base64 đã đầy đủ chưa và không có tiền tố data:image/...;base64,
ERROR_TOO_BIG_CAPTCHA_FILESIZE Tính vào tự động tạm dừng	Ảnh quá lớn	Nén hoặc thu nhỏ ảnh rồi gửi lại; toàn bộ nội dung yêu cầu không được vượt quá 6 MB
ERROR_IMAGE_TYPE_NOT_SUPPORTED Tính vào tự động tạm dừng	Định dạng ảnh không được hỗ trợ, hoặc ảnh không phải loại mà loại tác vụ này xử lý được. Chỉ cần xảy ra 1 lần là bị tạm dừng 30 phút	Dùng JPG hoặc PNG và đảm bảo ảnh phù hợp với loại tác vụ, ví dụ nhận dạng hình ảnh reCAPTCHA cần ảnh 100x100, 300x300 hoặc 450x450
ERROR_ILLEGAL_IMAGE Tính vào tự động tạm dừng	Kích thước ảnh không đáp ứng yêu cầu của loại tác vụ này	Điều chỉnh kích thước ảnh theo mô tả ở trang loại tác vụ
ERROR_PARSE_IMAGE_FAIL	Không giải mã được ảnh, thường do Base64 bị cắt cụt hoặc có tiền tố	Kiểm tra mã hóa Base64 và xóa tiền tố data: cùng các ký tự xuống dòng
ERROR_UNKNOWN_QUESTION	question bị sai, hoặc câu hỏi này hiện chưa được hỗ trợ	Đối chiếu với danh sách câu hỏi ở trang loại tác vụ. Với câu hỏi chưa được hỗ trợ, hãy liên hệ bộ phận hỗ trợ; câu hỏi mới thường được hỗ trợ trong vòng 3 ngày làm việc
ERROR_UNKNOW_450x450_QUESTION	Câu hỏi này hiện chưa được hỗ trợ với ảnh 4x4 (450x450)	Tải lại thử thách trên trang để lấy câu hỏi khác

Proxy

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_PROXY_CONNECT_REFUSED	Proxy từ chối kết nối	Kiểm tra địa chỉ, cổng và giao thức của proxy, và đảm bảo proxy cho phép kết nối từ bên ngoài (không phải địa chỉ cục bộ như 127.0.0.1)
ERROR_PROXY_CONNECT_TIMEOUT	Kết nối tới proxy bị hết thời gian chờ	Dùng proxy ổn định hơn
ERROR_PROXY_READ_TIMEOUT	Đọc dữ liệu qua proxy bị hết thời gian chờ	Dùng proxy nhanh hơn
ERROR_PROXY_BANNED	Proxy không khả dụng, hoặc IP của proxy bị trang web đích chặn	Dùng proxy khác
ERROR_PROXY_INCORRECT	Tham số proxy sai định dạng	Kiểm tra định dạng của proxyType, proxyAddress, proxyPort (hoặc chuỗi proxy)
ERROR_PROXY_TRANSPARENT	Proxy là proxy trong suốt (transparent) và làm lộ IP thật	Dùng proxy ẩn danh (elite)
ERROR_PROXY_NOT_AUTHORISED	Tên người dùng hoặc mật khẩu của proxy không đúng	Kiểm tra proxyLogin và proxyPassword (hoặc thông tin đăng nhập trong chuỗi proxy)
ERROR_PROXY_TLS_ERROR	Bắt tay TLS với proxy thất bại, thường do proxyType sai (ví dụ đặt https cho proxy http)	Kiểm tra lại giao thức của proxy
ERROR_PROXY_CONNECTION_FAILED	Không kết nối được tới máy chủ proxy	Kiểm tra địa chỉ và cổng của proxy, và đảm bảo proxy đang hoạt động bình thường

Máy chủ

Mã lỗi	Ý nghĩa	Cách xử lý
ERROR_SERVICE_UNAVALIABLE	Dịch vụ tạm thời không khả dụng (mã lỗi được viết là UNAVALIABLE)	Thử lại sau; nếu tiếp tục xảy ra, hãy liên hệ bộ phận hỗ trợ
ERROR_INTERNAL_SERVER_ERROR	Đã xảy ra lỗi máy chủ nội bộ	Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp taskId
ERROR_UNKNOWN	Lỗi chưa được phân loại	Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp taskId

Trường bổ sung

Phản hồi của một số lỗi có kèm các trường bổ sung:

Trường	Xuất hiện ở	Mô tả
retryAfter	ERROR_IP_BLOCKED_5MIN, các lỗi được cache	Cần chờ thêm bao nhiêu giây
blockReason	ERROR_IP_BLOCKED_5MIN	Mã lỗi đã kích hoạt việc tạm dừng
blockDetail	ERROR_IP_BLOCKED_5MIN	Loại yêu cầu, URL và sitekey của yêu cầu đã kích hoạt tạm dừng, giúp xác định nguyên nhân
cached	Các lỗi được cache	true nghĩa là đây là kết quả được cache, chưa thực sự nhận dạng
badRequest	Các lỗi được cache	Tham số đã trúng cache
limit	ERROR_THREADS_MAXIMUM	Giới hạn đồng thời hiện tại của bạn

Quy tắc về ngôn ngữ của errorDescription xem tại Yêu cầu và phản hồi.