Kesalahan dan Perbaikan Umum Solve reCAPTCHA v2

Sebagian besar kegagalan reCAPTCHA v2 terbagi dalam tiga kelompok: error tahap request (parameter salah dikirim ke API), masalah tahap hasil (masalah polling atau task tidak bisa di-solve), dan penolakan halaman target (API mengembalikan token valid tapi halaman mengabaikannya). Penyebab terbesarnya hampir selalu sama: googlekey salah, pageurl salah, callback tidak dijalankan, atau token kedaluwarsa.

Panduan ini menjelaskan setiap pola kegagalan umum dengan perbaikan yang tepat. Jika Anda baru mengenal solve reCAPTCHA v2, baca Cara Solve reCAPTCHA v2 dengan API terlebih dahulu.

Empat Titik Kegagalan Terbesar reCAPTCHA v2

Sebelum menggali kode error satu per satu, periksa ini terlebih dahulu — mencakup 80% kegagalan.

1. googlekey Salah atau Tidak Ada

googlekey (sitekey) berasal dari atribut data-sitekey pada widget reCAPTCHA atau parameter k di anchor URL. Jika nilai ini salah, kosong, atau disalin dari halaman lain, API akan langsung menolak task dengan ERROR_GOOGLEKEY atau ERROR_WRONG_GOOGLEKEY.

Cara menemukan kunci situs yang benar:

# 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 Salah

pageurl harus berupa URL persis tempat widget reCAPTCHA dimuat. Jika widget berada di dalam iframe yang dihosting di domain berbeda, Anda memerlukan URL iframe — bukan URL halaman induk. Mengirim URL yang salah menyebabkan ERROR_PAGEURL atau ERROR_BAD_TOKEN_OR_PAGEURL.

3. Callback Tidak Dijalankan

Beberapa halaman menggunakan fungsi callback JavaScript alih-alih field g-recaptcha-response yang tersembunyi. Jika Anda memasukkan token ke field tersembunyi tapi halaman mengharapkan callback, form tidak akan pernah disubmit. Periksa data-callback di widget atau properti callback di grecaptcha.render().

4. Token Kedaluwarsa atau Digunakan Ulang

Token reCAPTCHA berlaku untuk satu kali penggunaan dan kedaluwarsa setelah sekitar 2 menit. Jika otomatisasi Anda terlalu lama antara menerima token dan mengirimkan form, atau jika menggunakan kembali token, halaman target akan menolaknya secara diam-diam.

Error Tahap Request (in.php)

Error ini terjadi saat Anda mengirimkan task CAPTCHA ke https://ocr.captchaai.com/in.php.

Contoh: Request yang Benar dengan Error Handling

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}`);

Error Tahap Hasil (res.php)

Error ini terjadi saat polling https://ocr.captchaai.com/res.php untuk hasilnya.

Contoh: Polling dengan Error Handling yang Tepat

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`);
}

Penolakan Halaman Target

API mengembalikan token valid tapi situs target tetap menolaknya. Ini adalah kegagalan yang paling sulit di-debug karena API menganggap semuanya berhasil.

Token Di-inject ke Field yang Salah

Beberapa halaman mencari token di textarea g-recaptcha-response. Yang lain menggunakan grecaptcha.getResponse(). Yang lain mengharapkan callback. Jika Anda memilih metode inject yang salah, form submit akan gagal secara diam-diam.

Perbaikan: Periksa halaman untuk menentukan jalur yang diharapkan:

# 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()

Callback Tidak Terpicu

Jika widget memiliki data-callback="onSuccess" atau menggunakan grecaptcha.render() dengan properti callback, mengisi field tersembunyi saja tidak akan berhasil. Anda harus memanggil fungsi callback secara langsung.

Perbaikan: Temukan dan panggil callback:

// 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);
}

Token Kedaluwarsa

Jika lebih dari ~2 menit berlalu antara penerimaan token dan submit form, Google akan menolaknya. Ini umum terjadi di pipeline otomatisasi yang lambat.

Perbaikan: Submit form segera setelah menerima token. Jika alur Anda lambat, minta solve lebih dekat ke langkah submit, bukan di awal.

Widget Ada di Dalam iframe

Jika reCAPTCHA dimuat di dalam iframe dari domain berbeda, Anda harus menggunakan URL sumber iframe sebagai pageurl, bukan URL halaman induk. Error ERROR_BAD_TOKEN_OR_PAGEURL biasanya menandakan masalah ini.

Perbaikan: Periksa halaman, temukan iframe yang berisi reCAPTCHA, dan gunakan URL src iframe tersebut sebagai pageurl Anda.

Checklist Diagnosis Cepat

Pertanyaan Umum

Mengapa reCAPTCHA v2 gagal meskipun request terlihat benar?

Tiga penyebab paling umum: (1) pageurl tidak cocok dengan konteks widget sebenarnya — terutama saat widget berada di dalam iframe, (2) halaman mengharapkan fungsi callback tapi Anda hanya mengisi field tersembunyi, atau (3) token kedaluwarsa sebelum Anda mengirimkan form.

Apa error solve reCAPTCHA v2 yang paling umum?

Menggunakan googlekey salah atau pageurl salah. Hal ini umum terjadi saat widget reCAPTCHA dimuat di iframe pada domain atau subdomain berbeda — sitekey dan URL harus cocok dengan konteks iframe, bukan halaman induk.

Apa yang dimaksud CAPCHA_NOT_READY?

Artinya CAPTCHA masih dalam proses solve. Ini bukan error. Tunggu 5 detik dan polling res.php lagi. Waktu solve reCAPTCHA v2 umumnya 15–60 detik.

Apa yang harus dilakukan jika API mengembalikan token tapi halaman tetap menolaknya?

Periksa tiga hal secara berurutan: (1) Apakah halaman menggunakan callback? Cari data-callback di widget. (2) Apakah pageurl Anda benar — terutama jika widget ada di iframe? (3) Apakah ada jeda lebih dari 2 menit antara penerimaan dan penggunaan token?

Bagaimana cara menangani ERROR_CAPTCHA_UNSOLVABLE?

Submit task baru dengan parameter baru. Jangan retry task ID yang sama. Jika error ini berulang, verifikasi sitekey dan pageurl Anda cocok dengan halaman sebenarnya dan jenis CAPTCHA adalah reCAPTCHA v2 standar (bukan Enterprise — yang memerlukan parameter berbeda).

Perbaiki Alur Kerja reCAPTCHA v2 Anda

1. Verifikasi input Anda — ekstrak googlekey dari data-sitekey dan gunakan URL halaman yang tepat (periksa iframe)
2. Periksa metode inject — tentukan apakah halaman memerlukan field tersembunyi, callback, atau keduanya
3. Submit segera — gunakan token dalam 2 menit setelah menerimanya
4. Tambahkan error handling — gunakan contoh kode di atas untuk menangkap dan menangani setiap jenis error

Mulai solve reCAPTCHA v2 dengan CaptchaAI. Dapatkan API key Anda di captchaai.com/api.php.

Panduan Terkait

• Cara Solve reCAPTCHA v2 dengan API — tutorial lengkap langkah demi langkah
• Cara Solve Callback reCAPTCHA v2 dengan API — panduan khusus callback
• Referensi Kode Error CaptchaAI — daftar kode error lengkap