Các lỗi và cách khắc phục reCAPTCHA v2 phổ biến

Hầu hết các lỗi reCAPTCHA v2 đều thuộc ba nhóm: lỗi ở giai đoạn yêu cầu (tham số sai được gửi tới API), sự cố ở giai đoạn kết quả (vấn đề thăm dò ý kiến ​​hoặc nhiệm vụ không thể giải quyết) và từ chối trang đích (API trả về mã thông báo hợp lệ nhưng trang này bỏ qua nó). Thủ phạm lớn nhất hầu như luôn giống nhau: sai googlekey, pageurl không chính xác, thiếu thực thi lệnh gọi lại hoặc mã thông báo đã hết hạn.

Hướng dẫn này sẽ trình bày từng kiểu lỗi phổ biến với cách khắc phục chính xác cho từng kiểu. Nếu bạn chưa quen với cách giải reCAPTCHA v2, hãy đọcCách giải reCAPTCHA v2 bằng APIĐầu tiên.

Bốn điểm thất bại lớn nhất của reCAPTCHA v2

Trước khi tìm hiểu kỹ từng mã lỗi, hãy kiểm tra những mã lỗi này trước — chúng giải quyết được 80% lỗi.

1. googlekey sai hoặc thiếu

googlekey (sitekey) xuất phát từ thuộc tính data-sitekey trên tiện ích reCAPTCHA hoặc tham số k trong URL neo. Nếu giá trị này sai, trống hoặc được sao chép từ một trang khác, API sẽ từ chối tác vụ ngay lập tức bằng ERROR_GOOGLEKEY hoặc ERROR_WRONG_GOOGLEKEY.

Cách tìm khóa trang web chính xác:

# Look for data-sitekey in the page HTML
# <div class="g-recaptcha" data-sitekey="6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-"></div>

# Or find it in the anchor URL
# https://www.google.com/recaptcha/api2/anchor?k=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-

2. pageurl sai

pageurl phải là URL chính xác nơi tiện ích reCAPTCHA tải. Nếu tiện ích nằm trong iframe được lưu trữ trên một tên miền khác, bạn cần URL iframe — không phải URL trang gốc. Gửi sai URL sẽ gây ra ERROR_PAGEURL hoặc ERROR_BAD_TOKEN_OR_PAGEURL.

3. Lệnh gọi lại không được thực hiện

Một số trang sử dụng chức năng gọi lại JavaScript thay vì trường g-recaptcha-response ẩn. Nếu bạn đưa mã thông báo vào trường ẩn nhưng trang mong đợi một lệnh gọi lại thì biểu mẫu sẽ không bao giờ được gửi. Kiểm tra data-callback trên tiện ích hoặc thuộc tính callback trong grecaptcha.render().

4. Token đã hết hạn hoặc được sử dụng lại

Mã thông báo reCAPTCHA chỉ hợp lệ trong một lần sử dụng và hết hạn sau khoảng 2 phút. Nếu quá trình tự động hóa của bạn mất quá nhiều thời gian từ khi nhận mã thông báo đến khi gửi biểu mẫu hoặc nếu nó sử dụng lại mã thông báo thì trang đích sẽ âm thầm từ chối mã thông báo đó.

Lỗi giai đoạn yêu cầu (in.php)

Những lỗi này xảy ra khi bạn gửi tác vụ CAPTCHA tới https://ocr.captchaai.com/in.php.

Ví dụ: Yêu cầu đúng và xử lý lỗi

import requests

def submit_recaptcha_v2(api_key, sitekey, page_url):
    response = requests.get("https://ocr.captchaai.com/in.php", params={
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "json": 1
    })

    data = response.json()

    if data.get("status") == 1:
        return data["request"]  # task ID

    error = data.get("request", "UNKNOWN_ERROR")

    if error == "ERROR_WRONG_USER_KEY":
        raise ValueError("API key format is invalid. Must be 32 characters.")
    elif error == "ERROR_ZERO_BALANCE":
        raise RuntimeError("Account balance is zero. Top up at captchaai.com")
    elif error == "ERROR_PAGEURL":
        raise ValueError("pageurl parameter is missing from request")
    elif error in ("ERROR_GOOGLEKEY", "ERROR_WRONG_GOOGLEKEY"):
        raise ValueError(f"Invalid sitekey. Verify the data-sitekey value on the page.")
    elif error == "ERROR_BAD_TOKEN_OR_PAGEURL":
        raise ValueError("Sitekey/pageurl mismatch. Check if widget is in an iframe.")
    else:
        raise RuntimeError(f"API error: {error}")

# Usage
task_id = submit_recaptcha_v2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://staging.example.com/qa-login")
print(f"Task submitted: {task_id}")

async function submitRecaptchaV2(apiKey, sitekey, pageUrl) {
  const params = new URLSearchParams({
    key: apiKey,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageUrl,
    json: 1,
  });

  const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const data = await res.json();

  if (data.status === 1) return data.request;

  const error = data.request || "UNKNOWN_ERROR";
  const fixes = {
    ERROR_WRONG_USER_KEY: "API key format is invalid. Must be 32 characters.",
    ERROR_ZERO_BALANCE: "Account balance is zero. Top up at captchaai.com",
    ERROR_PAGEURL: "pageurl parameter is missing from request",
    ERROR_GOOGLEKEY: "Invalid sitekey. Check the data-sitekey attribute.",
    ERROR_BAD_TOKEN_OR_PAGEURL: "Sitekey/pageurl mismatch. Check iframe context.",
  };

  throw new Error(fixes[error] || `API error: ${error}`);
}

// Usage
const taskId = await submitRecaptchaV2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://staging.example.com/qa-login");
console.log(`Task submitted: ${taskId}`);

Lỗi giai đoạn kết quả (res.php)

Những lỗi này xảy ra khi thăm dò kết quả https://ocr.captchaai.com/res.php.

Ví dụ: Bỏ phiếu với cách xử lý lỗi thích hợp

import time
import requests

def poll_result(api_key, task_id, timeout=120):
    start = time.time()

    while time.time() - start < timeout:
        time.sleep(5)

        response = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1
        })

        data = response.json()

        if data.get("status") == 1:
            return data["request"]  # solved token

        error = data.get("request", "")

        if error == "CAPCHA_NOT_READY":
            continue  # normal — keep waiting
        elif error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable. Submit a new task with fresh params.")
        elif error in ("ERROR_WRONG_ID_FORMAT", "ERROR_WRONG_CAPTCHA_ID"):
            raise ValueError(f"Invalid task ID: {task_id}")
        else:
            raise RuntimeError(f"Polling error: {error}")

    raise TimeoutError(f"Solve timed out after {timeout}s")

# Usage
token = poll_result("YOUR_API_KEY", task_id)
print(f"Token: {token[:50]}...")

async function pollResult(apiKey, taskId, timeout = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    await new Promise((r) => setTimeout(r, 5000));

    const params = new URLSearchParams({
      key: apiKey,
      action: "get",
      id: taskId,
      json: 1,
    });

    const res = await fetch(`https://ocr.captchaai.com/res.php?${params}`);
    const data = await res.json();

    if (data.status === 1) return data.request;

    if (data.request === "CAPCHA_NOT_READY") continue;
    if (data.request === "ERROR_CAPTCHA_UNSOLVABLE")
      throw new Error("Unsolvable. Submit a new task.");
    throw new Error(`Polling error: ${data.request}`);
  }

  throw new Error(`Solve timed out after ${timeout / 1000}s`);
}

Từ chối trang mục tiêu

API trả về mã thông báo hợp lệ nhưng trang đích vẫn từ chối mã đó. Đây là những lỗi khó gỡ lỗi nhất vì API cho rằng mọi thứ đều hoạt động.

Mã thông báo được đưa vào sai trường

Một số trang tìm kiếm mã thông báo trong vùng văn bản g-recaptcha-response. Những người khác sử dụng grecaptcha.getResponse(). Những người khác mong đợi một cuộc gọi lại. Nếu bạn chọn sai phương pháp chèn, việc gửi biểu mẫu sẽ không thành công.

Khắc phục: Kiểm tra trang để xác định đường dẫn dự kiến:

# Method 1: Hidden field injection
driver.execute_script(
    'document.getElementById("g-recaptcha-response").innerHTML = arguments[0];',
    token
)

# Method 2: Callback execution (check data-callback attribute)
driver.execute_script(f'onCaptchaSuccess("{token}");')

# Method 3: Direct form field + submit
driver.execute_script(
    'document.querySelector("[name=g-recaptcha-response]").value = arguments[0];',
    token
)
driver.find_element("css selector", "form").submit()

Cuộc gọi lại không được kích hoạt

Nếu tiện ích có data-callback="onSuccess" hoặc sử dụng grecaptcha.render() với thuộc tính callback thì việc chỉ điền vào trường ẩn sẽ không có tác dụng gì. Bạn phải gọi trực tiếp hàm gọi lại.

Khắc phục: Tìm và gọi lại cuộc gọi:

// In browser console or Puppeteer/Playwright
// Check for data-callback
const widget = document.querySelector('.g-recaptcha');
const callbackName = widget?.getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

Mã thông báo đã hết hạn

Nếu thời gian từ lúc nhận mã thông báo đến lúc gửi biểu mẫu trôi qua quá ~2 phút, Google sẽ từ chối nó. Điều này thường xảy ra trong các đường ống tự động hóa chậm.

Khắc phục: Gửi biểu mẫu ngay sau khi nhận được mã thông báo. Nếu quy trình của bạn chậm, hãy yêu cầu giải quyết gần bước gửi hơn là ngay từ đầu.

Tiện ích nằm trong iframe

Nếu reCAPTCHA tải bên trong iframe từ một miền khác, bạn phải sử dụng URL nguồn iframe làm pageurl chứ không phải URL trang gốc. Lỗi ERROR_BAD_TOKEN_OR_PAGEURL thường báo hiệu sự cố này.

Khắc phục: Kiểm tra trang, tìm iframe chứa reCAPTCHA và sử dụng URL src của iframe đó làm pageurl của bạn.

Danh sách kiểm tra chẩn đoán nhanh

Câu hỏi thường gặp

Tại sao reCAPTCHA v2 không thành công ngay cả khi yêu cầu có vẻ chính xác?

Ba nguyên nhân phổ biến nhất là: (1) pageurl không khớp với bối cảnh tiện ích thực tế — đặc biệt khi tiện ích nằm trong iframe, (2) trang mong đợi chức năng gọi lại nhưng bạn chỉ điền vào trường ẩn hoặc (3) mã thông báo đã hết hạn trước khi bạn gửi biểu mẫu.

Lỗi giải quyết reCAPTCHA v2 phổ biến nhất là gì?

Sử dụng sai googlekey hoặc sai pageurl. Điều này đặc biệt phổ biến khi tiện ích reCAPTCHA tải trong iframe trên một miền hoặc miền phụ khác — khóa trang web và URL phải khớp với ngữ cảnh iframe chứ không phải trang gốc.

CAPCHA_NOT_READY có nghĩa là gì?

Điều đó có nghĩa là CAPTCHA vẫn đang được giải quyết. Đây không phải là một lỗi. Đợi 5 giây và thăm dò lại res.php. Thời gian giải quyết reCAPTCHA v2 thông thường là 15–60 giây.

Tôi nên làm gì nếu API trả về mã thông báo nhưng trang vẫn từ chối?

Kiểm tra ba điều theo thứ tự: (1) Trang có sử dụng lệnh gọi lại không? Tìm data-callback trên tiện ích. (2) pageurl của bạn có đúng không - đặc biệt nếu tiện ích nằm trong iframe? (3) Thời gian nhận và sử dụng mã thông báo có vượt quá 2 phút không?

Làm cách nào để xử lý 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 này xảy ra nhiều lần, hãy xác minh khóa trang web và url trang của bạn khớp với trang thực tế và loại CAPTCHA là reCAPTCHA v2 tiêu chuẩn (không phải Doanh nghiệp — yêu cầu các tham số khác nhau).

Sửa quy trình làm việc reCAPTCHA v2 của bạn

1. Xác minh thông tin đầu vào của bạn — trích xuất googlekey từ data-sitekey và sử dụng URL trang chính xác (kiểm tra iframe)
2. Kiểm tra phương pháp chèn — xác định xem trang có yêu cầu trường ẩn, lệnh gọi lại hay cả hai không
3. Gửi ngay — sử dụng mã thông báo trong vòng 2 phút kể từ khi nhận được
4. Thêm xử lý lỗi — sử dụng các ví dụ về mã ở trên để phát hiện và xử lý mọi loại lỗi

Bắt đầu giải reCAPTCHA v2 bằngBộ giải CaptchaAI. Nhận khóa API của bạn từcaptchaai.com/api.php.

Hướng dẫn liên quan

• Cách giải reCAPTCHA v2 bằng API- hướng dẫn từng bước đầy đủ
• Cách giải quyết cuộc gọi lại reCAPTCHA v2 bằng API- hướng dẫn gọi lại cụ thể
• Giải thích về thử thách lưới reCAPTCHA— các thách thức về lưới điện hoạt động như thế nào
• Tham khảo mã lỗi CaptchaAI- danh sách mã lỗi đầy đủ