Các lỗi và cách sửa lỗi phổ biến của reCAPTCHA v2 Enterprise

Token reCAPTCHA v2 Enterprise bị site đích từ chối dù CaptchaAI trả về status: 1? Trong phần lớn trường hợp, nguyên nhân là đúng một tham số bị thiếu: enterprise=1. Đây là lỗi phổ biến nhất khi team QA tại công ty outsourcing ở TP.HCM hay Hà Nội tích hợp CaptchaAI cho ứng dụng dùng reCAPTCHA Enterprise — thường gặp ở trang ngân hàng, cổng thanh toán hoặc dịch vụ công dùng bản Enterprise trả phí của Google.

Ba nguyên nhân chiếm phần lớn lỗi Enterprise trong thực tế:

• Thiếu tham số enterprise=1 trong request
• Bỏ sót data-s khi trang có gắn thuộc tính này
• Nhận diện sai widget là tiêu chuẩn trong khi trang đang chạy Enterprise (hoặc ngược lại)

Bài viết này liệt kê lỗi thường gặp khi giải reCAPTCHA v2 Enterprise qua API CaptchaAI, kèm bảng mã lỗi dùng chung với v2 tiêu chuẩn. Nếu chưa chắc trang đang test dùng Enterprise hay tiêu chuẩn, đọc Cách xác định việc triển khai reCAPTCHA Enterprise trước.

Checklist sửa nhanh trong 4 bước

Trước khi đọc chi tiết từng lỗi, chạy qua bốn bước này — phần lớn trường hợp status: 1 bị site từ chối được xử lý xong ở bước 2:

1. Xác minh đúng loại triển khai — tìm enterprise.js trong thẻ script của trang
2. Thêm enterprise=1 vào mọi request gửi tới CaptchaAI
3. Kiểm tra data-s — đưa vào request nếu trang có thuộc tính này
4. Submit token ngay khi nhận được — token Enterprise cũng hết hạn sau khoảng 2 phút, không nên giữ lại

Lấy API key tại captchaai.com/api.php.

reCAPTCHA v2 Enterprise khác bản tiêu chuẩn ở đâu

Về mặt kỹ thuật, Enterprise và tiêu chuẩn dùng chung cơ chế token nhưng khác script, đối tượng JS và endpoint xác minh:

Hai dòng cuối bảng là nguyên nhân của gần như toàn bộ lỗi Enterprise dưới đây.

3 lỗi chỉ xảy ra với reCAPTCHA Enterprise

Quên tham số enterprise=1

Request trả status: 1 và token đúng định dạng, nhưng form trên site đích vẫn báo lỗi xác thực — dấu hiệu điển hình của task gửi thiếu enterprise=1. CaptchaAI vẫn giải bình thường như v2 tiêu chuẩn, chỉ khác là backend Enterprise xác minh qua API riêng nên từ chối thẳng token chuẩn đó.

Thêm enterprise=1 (kiểu số nguyên) vào request để sửa:

import requests

response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
    "pageurl": "https://staging.example.com/qa-login",
    "enterprise": 1,
    "json": 1
})

data = response.json()
task_id = data["request"]

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  method: "userrecaptcha",
  googlekey: "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
  pageurl: "https://staging.example.com/qa-login",
  enterprise: 1,
  json: 1,
});

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

Bỏ sót tham số data-s

ERROR_BAD_PARAMETERS, hoặc token bị từ chối dù mọi thứ khác đều đúng, thường bắt nguồn từ thuộc tính data-s trên div reCAPTCHA mà một số triển khai Enterprise gắn thêm — đây là token phiên bổ sung, không phải tùy chọn. Thiếu nó trong request, bước xác minh sẽ thất bại dù CaptchaAI vẫn trả token bình thường.

Kiểm tra HTML của trang để tìm data-s và đưa vào request nếu có:

# Look for: <div class="g-recaptcha" data-sitekey="..." data-s="..."></div>
response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": sitekey,
    "pageurl": page_url,
    "enterprise": 1,
    "data-s": data_s_value,  # Include if present on the page
    "json": 1
})

Nhận diện sai loại widget

Token khi hoạt động khi không, hoặc luôn bị từ chối bất kể thử lại bao nhiêu lần — dấu hiệu widget thực chất là Enterprise nhưng bạn xử lý như tiêu chuẩn (hoặc ngược lại), thường xảy ra khi copy code mẫu từ dự án khác mà quên kiểm tra lại loại widget của trang mới.

Đọc thẳng mã nguồn HTML của trang để xác nhận:

// Enterprise uses enterprise.js
// <script src="https://www.google.com/recaptcha/enterprise.js?render=SITEKEY"></script>

// Standard uses api.js
// <script src="https://www.google.com/recaptcha/api.js"></script>

// Also check the JS object:
// Enterprise: grecaptcha.enterprise.render(...)
// Standard: grecaptcha.render(...)

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

enterprise=1 để làm gì trong request CaptchaAI?

Đây là cờ bắt buộc báo cho CaptchaAI biết widget đang chạy trên backend Enterprise. Thiếu cờ này, CaptchaAI vẫn giải bình thường nhưng trả token v2 chuẩn — loại token backend Enterprise luôn từ chối.

Tham số data-s lấy ở đâu và khi nào cần?

Xem trực tiếp trong HTML: <div class="g-recaptcha" data-sitekey="..." data-s="..."></div>. Không phải widget Enterprise nào cũng có thuộc tính này — chỉ đưa vào request khi thực sự tồn tại trên trang. Nếu trang có data-s mà bạn bỏ qua, token thường bị từ chối dù CaptchaAI báo giải thành công.

reCAPTCHA v2 Enterprise tốn bao nhiêu thread trên CaptchaAI?

Enterprise dùng chung cơ chế giá theo thread như mọi loại CAPTCHA khác trên CaptchaAI, không có phụ phí riêng theo loại. Gói BASIC ($15/tháng, 5 thread) đủ cho khối lượng test nhỏ; nếu chạy nhiều luồng QA song song, cân nhắc ADVANCE ($90/tháng, 50 thread) hoặc cao hơn tùy tải thực tế.

Token reCAPTCHA Enterprise hết hạn sau bao lâu?

Khoảng 2 phút kể từ lúc CaptchaAI trả kết quả, giống hệt v2 tiêu chuẩn. Submit token vào form ngay khi nhận được thay vì lưu lại dùng sau.

CaptchaAI có hỗ trợ reCAPTCHA v3 Enterprise không?

Có. CaptchaAI hỗ trợ cả reCAPTCHA v3 Enterprise lẫn v2 Enterprise, cùng dùng enterprise=1. Khác biệt là v3 Enterprise trả về điểm rủi ro (score) thay vì checkbox tương tác.

Mã lỗi dùng chung với reCAPTCHA v2 tiêu chuẩn

Ngoài ba lỗi riêng của Enterprise ở trên, phần còn lại trùng với v2 tiêu chuẩn:

Lỗi liên quan tới API key và số dư

Lỗi liên quan tới trang và task

Quy trình giải hoàn chỉnh có xử lý lỗi

Đoạn code dưới đây gộp cả hai lỗi Enterprise thường gặp nhất (enterprise=1 và data-s) vào một hàm submit → polling → trả token, kèm xử lý lỗi cho từng bước:

import requests
import time

def solve_recaptcha_v2_enterprise(api_key, sitekey, page_url, data_s=None):
    params = {
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "enterprise": 1,
        "json": 1
    }
    if data_s:
        params["data-s"] = data_s

    response = requests.get("https://ocr.captchaai.com/in.php", params=params)
    data = response.json()

    if data.get("status") != 1:
        raise RuntimeError(f"Submit failed: {data.get('request')}")

    task_id = data["request"]

    for _ in range(40):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key, "action": "get", "id": task_id, "json": 1
        }).json()

        if result.get("status") == 1:
            return result["request"]
        if result.get("request") == "CAPCHA_NOT_READY":
            continue
        raise RuntimeError(f"Solve failed: {result.get('request')}")

    raise TimeoutError("Solve timed out after 200 seconds")

token = solve_recaptcha_v2_enterprise("YOUR_API_KEY", "SITEKEY", "https://staging.example.com/qa-login")

async function solveRecaptchaV2Enterprise(apiKey, sitekey, pageUrl, dataS) {
  const params = new URLSearchParams({
    key: apiKey, method: "userrecaptcha", googlekey: sitekey,
    pageurl: pageUrl, enterprise: 1, json: 1,
  });
  if (dataS) params.set("data-s", dataS);

  const submitRes = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const submitData = await submitRes.json();
  if (submitData.status !== 1) throw new Error(`Submit failed: ${submitData.request}`);

  const taskId = submitData.request;
  for (let i = 0; i < 40; i++) {
    await new Promise(r => setTimeout(r, 5000));
    const res = await fetch(`https://ocr.captchaai.com/res.php?${new URLSearchParams({
      key: apiKey, action: "get", id: taskId, json: 1,
    })}`);
    const data = await res.json();
    if (data.status === 1) return data.request;
    if (data.request === "CAPCHA_NOT_READY") continue;
    throw new Error(`Solve failed: ${data.request}`);
  }
  throw new Error("Timed out after 200s");
}

Hướng dẫn liên quan

• Cách xác định việc triển khai reCAPTCHA Enterprise
• Cách giải reCAPTCHA v2 bằng API
• So sánh reCAPTCHA v2 tiêu chuẩn và Enterprise
• Tham khảo mã lỗi CaptchaAI