Trang này ghi lại mọi mã lỗi mà API CaptchaAI có thể trả về, được sắp xếp theo điểm cuối. Sử dụng nó để chẩn đoán các yêu cầu không thành công, thực hiện xử lý lỗi thích hợp và tránh các lỗi phổ biến.
API CaptchaAI có hai điểm cuối:
in.php— gửi tác vụ CAPTCHA (lỗi xảy ra tại thời điểm gửi)res.php— thăm dò kết quả (xảy ra lỗi khi truy xuất kết quả)
Khi bạn đưa json=1 vào yêu cầu của mình, lỗi sẽ trả về dưới dạng JSON:
{"status": 0, "request": "ERROR_CODE_HERE"}
Nếu không có json=1, lỗi sẽ trả về dưới dạng văn bản thuần túy: ERROR_CODE_HERE
Quy tắc xử lý lỗi nhanh
Trước khi tham khảo đầy đủ, đây là ba quy tắc xử lý 90% trường hợp:
| Mẫu lỗi | hành động |
|---|---|
CAPCHA_NOT_READY |
Bình thường — thăm dò lại sau 5 giây |
Bất kỳ ERROR_ nào bắt đầu bằng các vấn đề về tham số/format |
Hãy sửa yêu cầu của bạn - không thử lại cùng một yêu cầu |
Lỗi máy chủ (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) |
Thử lại sau 10 giây với thời gian chờ theo cấp số nhân |
Gửi lỗi (in.php)
Những lỗi này xảy ra khi bạn gửi tác vụ CAPTCHA mới.
ERROR_WRONG_USER_KEY
Nguyên nhân: Tham số key có định dạng không chính xác. Khóa API CaptchaAI có 32 ký tự.
Sửa chữa:
- Kiểm tra xem khóa của bạn có chính xác 32 ký tự không.
- Xác minh rằng không có khoảng trắng thừa hoặc ngắt dòng.
- Sao chép chìa khóa trực tiếp từcaptchaai.com/api.php.
{
"key": "abc123... "
}
{
"key": "abc12345678901234567890123456789a"
}
ERROR_KEY_DOES_NOT_EXIST
Lý do: Key API không khớp với bất kỳ tài khoản nào trong hệ thống.
Sửa chữa:
- Đăng nhập vàocaptchaai.comvà sao chép khóa từ bảng điều khiển của bạn.
- Đảm bảo bạn đang sử dụng đúng khóa của tài khoản.
- Nếu bạn mới tạo tài khoản, hãy đợi vài phút để key kích hoạt.
ERROR_ZERO_BALANCE
Lý do: Tài khoản của bạn không có chủ đề nào để nhận nhiệm vụ.
Sửa chữa:
- Đợi các tác vụ hiện đang chạy hoàn tất (các luồng sẽ giải phóng).
- Nâng cấp gói của bạn để có nhiều chủ đề đồng thời hơn.
- Kiểm tra số dư tài khoản của bạn tạicaptchaai.com/api.php.
Đây không phải lúc nào cũng là lỗi hết tiền. Nó cũng có thể có nghĩa là tất cả các chủ đề của bạn hiện đang bị chiếm đóng. Nếu bạn có gói một luồng và một tác vụ đang chạy thì các lần gửi mới sẽ trả về lỗi này cho đến khi tác vụ đầu tiên hoàn thành.
ERROR_PAGEURL
Lý do: Tham số pageurl bị thiếu hoặc trống. Tham số này là bắt buộc đối với CAPTCHA dựa trên mã thông báo (reCAPTCHA, Cloudflare Turnstile, GeeTest, v.v.).
Khắc phục: Thêm URL đầy đủ của trang tải CAPTCHA, bao gồm cả giao thức:
{
"pageurl": ""
}
{
"pageurl": "https://staging.example.com/qa-login"
}
ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY
Lý do: Tham số googlekey (sitekey) trống, không đúng định dạng hoặc bị thiếu.
Sửa chữa:
- Trích xuất lại khóa trang web từ thuộc tính
data-sitekeycủa trang đích hoặc tham số URL neo reCAPTCHAk. - Đảm bảo giá trị không trống hoặc bị cắt bớt.
{
"googlekey": ""
}
{
"googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
ERROR_BAD_TOKEN_OR_PAGEURL
Lý do: Sự kết hợp giữa googlekey (sitekey) và pageurl không hợp lệ. Khóa trang web chưa được đăng ký cho URL trang đã cho.
Các nguyên nhân thường gặp:
- Tiện ích reCAPTCHA tải bên trong iframe trên một tên miền phụ khác. Bạn đang sử dụng URL trang mẹ thay vì URL iframe.
- Khóa trang web thuộc về một trang hoặc tên miền khác.
- Khóa trang web được trích xuất từ môi trường Development/staging.
Sửa chữa:
- Nếu reCAPTCHA nằm trong iframe, hãy sử dụng URL
srccủa iframe đó làmpageurl. - Xác minh mã khóa trang web từ trang sản xuất trực tiếp.
- Kiểm tra cả hai giá trị bằng cách tải URL neo reCAPTCHA theo cách thủ công:
https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY
ERROR_TOO_BIG_CAPTCHA_FILESIZE
Lý do: Hình tải lên vượt quá kích thước tối đa cho phép.
Khắc phục: Nén hoặc thay đổi kích thước hình ảnh trước khi gửi. Sử dụng JPEG cho ảnh, PNG cho ảnh chụp màn hình.
ERROR_ZERO_CAPTCHA_FILESIZE
Lý do: Tệp hình ảnh quá nhỏ (dưới 100 byte), cho thấy quá trình tải lên trống hoặc bị hỏng.
Khắc phục: Xác minh rằng bạn đang gửi dữ liệu hình ảnh thực tế chứ không phải tệp trống hoặc chuỗi base64 bị hỏng.
ERROR_WRONG_FILE_EXTENSION
Lý do: File tải lên có phần mở rộng không được hỗ trợ. Được hỗ trợ: jpg, jpeg, png, gif.
Khắc phục: Chuyển đổi hình ảnh sang định dạng được hỗ trợ trước khi tải lên.
ERROR_IMAGE_TYPE_NOT_SUPPORTED
Lý do: Máy chủ không thể xác định loại hình ảnh từ nội dung tệp.
Khắc phục: Chuyển đổi sang định dạng chuẩn (PNG hoặc JPEG) và đảm bảo tệp không bị hỏng.
ERROR_UPLOAD
Lý do: Máy chủ không thể đọc tệp đã tải lên hoặc tải trọng base64.
Sửa chữa:
- Để tải tệp lên: hãy xác minh mã hóa dữ liệu biểu mẫu nhiều phần của bạn.
- Đối với base64: xác minh chuỗi base64 đã hoàn chỉnh và được mã hóa chính xác.
- Kiểm tra bằng một hình ảnh nổi tiếng để loại trừ lỗi hỏng tệp.
ERROR_BAD_PROXY
Lý do: Proxy bạn cung cấp không thể truy cập được hoặc đã bị hệ thống đánh dấu là không hợp lệ.
Sửa chữa:
- Kiểm tra proxy một cách độc lập - nó có thể kết nối với trang đích không?
- Hãy thử một proxy khác.
- Xác minh định dạng:
login:password@IP:PORThoặcIP:PORTcho proxy được xác thực IP.
Việc sử dụng proxy phải được kích hoạt trên tài khoản của bạn. Hãy liên hệ với bộ phận hỗ trợ CaptchaAI nếu bạn chưa thực hiện việc này.
ERROR_BAD_PARAMETERS
Lý do: Thiếu tham số bắt buộc hoặc sai kiểu dữ liệu.
Khắc phục: Kiểm tra tài liệu API để biết loại CAPTCHA cụ thể mà bạn đang giải quyết và xác minh rằng tất cả các tham số bắt buộc đều có:
| Loại CAPTCHA | Thông số bắt buộc |
|---|---|
| reCAPTCHA v2/v3 | key, method=userrecaptcha, googlekey, pageurl |
| Cloudflare Turnstile | key, method=turnstile, sitekey, pageurl |
| Cloudflare Challenge | key, method=cloudflare_challenge, pageurl, proxy, proxytype |
| GeeTest v3 | key, method=geetest, gt, challenge, pageurl |
| BLS | key, method=bls, body, textinstructions |
| Bình thường/image | key, method=post, file hoặc body |
IP_CẤM
Lý do: IP của bạn đã bị cấm tạm thời sau nhiều lần xác thực không thành công.
Khắc phục: Đợi khoảng 5 phút rồi thử lại bằng thông tin xác thực chính xác. Đừng tiếp tục gửi yêu cầu với các khóa API sai.
ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR
Lý do: Đã xảy ra lỗi tạm thời phía máy chủ.
Khắc phục: Đợi 10 giây và thử lại. Sử dụng thời gian chờ theo cấp số nhân cho các lỗi lặp lại:
import time
retry_delay = 10
for attempt in range(5):
response = submit_captcha()
if response.get("status") == 1:
break
time.sleep(retry_delay)
retry_delay *= 2 # 10s, 20s, 40s, 80s, 160s
Lỗi bỏ phiếu (res.php)
Những lỗi này xảy ra khi bạn kiểm tra trạng thái của một tác vụ đã gửi.
CAPCHA_NOT_READY
Đây không phải là lỗi. Điều đó có nghĩa là quá trình giải quyết vẫn đang được tiến hành.
Hành động: Đợi 5 giây và thăm dò lại.
if result.get("request") == "CAPCHA_NOT_READY":
time.sleep(5)
continue # poll again
Hướng dẫn tính thời gian: | Loại CAPTCHA | Cuộc thăm dò đầu tiên sau | Khoảng thời gian thăm dò ý kiến | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 giây | 5 giây | | Cloudflare Turnstile | 15 giây | 5 giây | | Cloudflare Challenge | 20 giây | 5 giây | | GeeTest v3 | 15 giây | 5 giây | | Bình thường/image CAPTCHA | 5 giây | 5 giây |
ERROR_CAPTCHA_UNSOLVABLE
Lý do: CaptchaAI không thể giải CAPTCHA sau nhiều lần thử.
Lý do thường gặp:
- Loại CAPTCHA không được hỗ trợ hoặc thông số sai.
- Thử thách bị hỏng hoặc hết hạn.
- Đối với các giải pháp dựa trên proxy: proxy quá chậm hoặc không thể truy cập được.
- Trang web đã thay đổi cách triển khai CAPTCHA.
Sửa chữa:
- Xác minh các thông số của bạn (sitekey, pageurl, phương thức) là chính xác.
- Gửi lại với một yêu cầu mới.
- Nếu sử dụng proxy, hãy thử một proxy khác.
- Nếu lỗi vẫn tiếp diễn thì trang web có thể đã thay đổi — hãy trích xuất lại khóa trang và url trang.
Đừng thử lại cùng một ID nhiệm vụ. Gửi một nhiệm vụ mới với các thông số mới.
LỖI_WRONG_ID_FORMAT
Lý do: ID hình ảnh xác thực chỉ được có dạng số.
Khắc phục: Xác minh rằng bạn đang gửi ID chính xác được in.php trả về (chỉ các chữ số, không có ký tự phụ).
ERROR_WRONG_CAPTCHA_ID
Lý do: ID nhiệm vụ không tồn tại hoặc đã hết hạn.
Sửa chữa:
- Xác minh rằng bạn đang bỏ phiếu bằng ID được trả về khi gửi.
- ID nhiệm vụ có thể hết hạn sau một thời gian dài — hãy gửi lại nếu nhiệm vụ quá cũ.
ERROR_EMPTY_ACTION
Lý do: Tham số action bị thiếu hoặc trống trong yêu cầu bỏ phiếu của bạn.
Khắc phục: Thêm action=get vào yêu cầu res.php của bạn:
params = {
"key": api_key,
"action": "get", # Required
"id": captcha_id,
"json": 1,
}
ERROR_PROXY_CONNECTION_FAILED
Lý do: Trình giải quyết không thể kết nối với trang đích thông qua proxy của bạn.
Sửa chữa:
- Proxy có thể tạm thời ngừng hoạt động — hãy thử một proxy khác.
- Trang web mục tiêu có thể đang chặn IP proxy.
- Xác minh proxy thực sự có thể tiếp cận trang đích.
ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST
Những lỗi này cũng có thể xuất hiện trên res.php — nguyên nhân và cách khắc phục tương tự như các lỗi gửi ở trên.
Mẫu xử lý lỗi
Sao chép mẫu này để xử lý lỗi hiệu quả bằng bất kỳ ngôn ngữ nào:
Python
import time
import requests
API_KEY = "YOUR_API_KEY"
SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"
# Errors that should not be retried (fix the request first)
NO_RETRY_ERRORS = {
"ERROR_WRONG_USER_KEY",
"ERROR_KEY_DOES_NOT_EXIST",
"ERROR_PAGEURL",
"ERROR_WRONG_GOOGLEKEY",
"ERROR_GOOGLEKEY",
"ERROR_BAD_TOKEN_OR_PAGEURL",
"ERROR_BAD_PARAMETERS",
"ERROR_WRONG_FILE_EXTENSION",
"ERROR_IMAGE_TYPE_NOT_SUPPORTED",
"IP_BANNED",
}
# Errors that can be retried
RETRY_ERRORS = {
"ERROR_ZERO_BALANCE",
"ERROR_SERVER_ERROR",
"ERROR_INTERNAL_SERVER_ERROR",
"ERROR_UPLOAD",
}
def solve_captcha(submit_data, max_retries=3, max_polls=60):
"""Submit and solve a CAPTCHA with full error handling."""
# Submit with retry logic
for attempt in range(max_retries):
resp = requests.post(SUBMIT_URL, data={**submit_data, "json": 1}, timeout=30)
resp.raise_for_status()
data = resp.json()
if data.get("status") == 1:
captcha_id = data["request"]
break
error = data.get("request", "UNKNOWN")
if error in NO_RETRY_ERRORS:
raise ValueError(f"Fatal error (fix request): {error}")
if error in RETRY_ERRORS and attempt < max_retries - 1:
time.sleep(10 * (2 ** attempt))
continue
raise RuntimeError(f"Submit failed: {error}")
else:
raise RuntimeError("Submit failed after max retries")
# Poll for result
time.sleep(15)
for _ in range(max_polls):
resp = requests.get(
RESULT_URL,
params={"key": API_KEY, "action": "get", "id": captcha_id, "json": 1},
timeout=30,
)
data = resp.json()
if data.get("request") == "CAPCHA_NOT_READY":
time.sleep(5)
continue
if data.get("status") == 1:
return data["request"]
error = data.get("request", "UNKNOWN")
if error == "ERROR_CAPTCHA_UNSOLVABLE":
raise RuntimeError("CAPTCHA unsolvable — resubmit with fresh parameters")
raise RuntimeError(f"Poll error: {error}")
raise TimeoutError("Solve timed out")
Node.js
const NO_RETRY_ERRORS = new Set([
"ERROR_WRONG_USER_KEY",
"ERROR_KEY_DOES_NOT_EXIST",
"ERROR_PAGEURL",
"ERROR_WRONG_GOOGLEKEY",
"ERROR_BAD_TOKEN_OR_PAGEURL",
"ERROR_BAD_PARAMETERS",
"IP_BANNED",
]);
async function solveCaptcha(submitData, maxRetries = 3, maxPolls = 60) {
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// Submit with retry
let captchaId;
for (let attempt = 0; attempt < maxRetries; attempt++) {
const resp = await fetch("https://ocr.captchaai.com/in.php", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ ...submitData, json: "1" }),
});
const data = await resp.json();
if (data.status === 1) {
captchaId = data.request;
break;
}
if (NO_RETRY_ERRORS.has(data.request)) {
throw new Error(`Fatal error: ${data.request}`);
}
if (attempt < maxRetries - 1) {
await sleep(10_000 * 2 ** attempt);
continue;
}
throw new Error(`Submit failed: ${data.request}`);
}
// Poll for result
await sleep(15_000);
for (let i = 0; i < maxPolls; i++) {
const resp = await fetch(
`https://ocr.captchaai.com/res.php?${new URLSearchParams({
key: submitData.key,
action: "get",
id: captchaId,
json: "1",
})}`
);
const data = await resp.json();
if (data.request === "CAPCHA_NOT_READY") {
await sleep(5_000);
continue;
}
if (data.status === 1) return data.request;
throw new Error(`Poll error: ${data.request}`);
}
throw new Error("Solve timed out");
}
Câu hỏi thường gặp
CAPCHA_NOT_READY có phải là lỗi không?
Không. Điều đó có nghĩa là việc giải quyết vẫn đang được tiến hành. Đợi 5 giây và thăm dò lại. Điều này là bình thường đối với mọi loại CAPTCHA.
Tôi nên làm gì khi nhận được ERROR_CAPTCHA_UNSOLVABLE?
Gửi một nhiệm vụ mới với các thông số mới. Đừng thử lại cùng một ID nhiệm vụ. Nếu lỗi xảy ra nhiều lần, hãy xác minh khóa trang web và url trang của bạn là chính xác và loại CAPTCHA được hỗ trợ.
Làm cách nào để biết lỗi có thể thử lại được hay không?
Không thể thử lại các lỗi Parameter/format (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, v.v.) - trước tiên hãy sửa yêu cầu. Lỗi máy chủ (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) có thể thử lại với thời gian chờ theo cấp số nhân. ERROR_ZERO_BALANCE có thể thử lại sau khi chờ các luồng giải phóng.
Tại sao tôi nhận được ERROR_BAD_PROXY cho Cloudflare Challenge?
Cloudflare Challenge yêu cầu proxy hoạt động. Proxy phải có khả năng tiếp cận trang web mục tiêu. Hãy kiểm tra nó một cách độc lập, sau đó thử một proxy khác nếu không thành công. Đồng thời đảm bảo việc sử dụng proxy được bật trên tài khoản CaptchaAI của bạn.
Tôi có thể tìm khóa API của mình ở đâu?
Đăng nhập vàocaptchaai.comvà đi đếncaptchaai.com/api.php. Khóa API gồm 32 ký tự của bạn được hiển thị trên trang tổng quan.
Hướng dẫn liên quan
- CaptchaAI Bắt đầu nhanh— giải quyết vấn đề đầu tiên của bạn
- Cách giải reCAPTCHA v2 bằng API- hướng dẫn đầy đủ về reCAPTCHA v2
- Cách giải Cloudflare Challenge bằng API— giải quyết Cloudflare cần có proxy
- Các lỗi giải quyết reCAPTCHA v2 thường gặp— khắc phục sự cố dành riêng cho reCAPTCHA
