Kesalahan dan Perbaikan Umum Solve reCAPTCHA v2

reCAPTCHA v2 di CaptchaAI hampir selalu gagal karena salah satu dari empat hal: googlekey yang salah, pageurl yang tidak sesuai konteks widget, callback yang tidak terpicu, atau token yang sudah kedaluwarsa saat disubmit. Task yang ditolak di in.php gampang dikenali — API langsung mengembalikan kode error. Yang jauh lebih menjebak adalah saat in.php dan res.php sama-sama melaporkan sukses dan token-nya valid, tapi halaman target tetap menolaknya.

Kalau worker Anda lintas region — browser jalan di satu region cloud, staging QA di region lain — latency jaringan saja bisa memakan sebagian jatah 2 menit umur token, sebelum antrean browser dan proses form ikut dihitung.

Panduan ini membedah setiap pola kegagalan itu, lengkap dengan perbaikannya. Baru pertama kali solve reCAPTCHA v2 dengan CaptchaAI? Mulai dari Cara Solve reCAPTCHA v2 dengan API dulu.

Checklist Kilat: Diagnosis reCAPTCHA v2 dalam 60 Detik

Cocokkan dulu gejala Anda dengan daftar ini sebelum menelusuri kode error satu per satu — cakupannya hampir semua kasus yang masuk ke tim support.

• ERROR_GOOGLEKEY atau ERROR_WRONG_GOOGLEKEY — apakah sitekey disalin persis dari atribut data-sitekey?
• ERROR_PAGEURL — apakah URL halaman yang dikirim sudah lengkap, bukan hanya domain?
• ERROR_BAD_TOKEN_OR_PAGEURL — apakah widget-nya sebenarnya ada di dalam iframe? Kalau ya, pakai URL iframe.
• CAPCHA_NOT_READY menetap lebih dari 3 menit — wajar untuk challenge berat; naikkan timeout ke 180 detik dulu.
• ERROR_CAPTCHA_UNSOLVABLE — kirim task baru dengan parameter segar; kalau berulang, cek ulang sitekey dan pageurl.
• Token kembali tapi halaman diam saja — cek atribut data-callback, lalu panggil fungsi callback-nya langsung.
• Token kembali tapi form tetap gagal — kemungkinan token sudah kedaluwarsa (>2 menit); submit lebih cepat.
• Kegagalan yang muncul sesekali — tambahkan logika retry dengan task ID baru, jangan retry ID yang sama.

Empat Penyebab Utama reCAPTCHA v2 Gagal Diselesaikan

Kalau checklist di atas belum menjawab masalah Anda, empat penyebab berikut mencakup sekitar 80% dari semua kegagalan reCAPTCHA v2.

1. googlekey Salah atau Kosong

googlekey (sitekey) diambil dari atribut data-sitekey pada widget reCAPTCHA, atau dari parameter k di anchor URL-nya.

Kalau nilainya salah, kosong, atau tersalin dari halaman lain, API langsung menolak task dengan ERROR_GOOGLEKEY atau ERROR_WRONG_GOOGLEKEY — tidak ada proses solve sama sekali. Begini cara mengambil sitekey 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-

Sudah pasti nilainya benar tapi error masih muncul? Lanjut ke penyebab berikutnya.

2. pageurl Tidak Sesuai Konteks Widget

pageurl harus persis URL tempat widget reCAPTCHA dimuat. Kalau widget-nya berada di dalam iframe yang di-host di domain lain, yang Anda butuhkan adalah URL iframe tersebut, bukan URL halaman induk. Mengirim URL yang salah memicu ERROR_PAGEURL atau ERROR_BAD_TOKEN_OR_PAGEURL.

3. Callback dan Token: Dua Penyebab Klasik Lainnya

• Callback tidak terpicu — sebagian halaman memakai fungsi callback JavaScript, bukan field tersembunyi g-recaptcha-response. Kalau Anda hanya mengisi field tersembunyi padahal halaman menunggu callback dipanggil, form tidak akan pernah tersubmit. Cek atribut data-callback di widget, atau properti callback pada grecaptcha.render().
• Token kedaluwarsa atau dipakai ulang — token reCAPTCHA hanya berlaku sekali pakai dan kedaluwarsa dalam sekitar 2 menit. Kalau pipeline Anda lambat antara menerima token dan mengirim form, atau token yang sama dipakai ulang, halaman target menolaknya secara diam-diam.

Error di in.php: Task Ditolak Sebelum Diproses

Error ini muncul saat Anda mengirim task CAPTCHA ke https://ocr.captchaai.com/in.php. Sifatnya selalu di sisi request — task ditolak sebelum sempat masuk antrean solve.

Daftar Kode Error in.php

Begini bentuk request yang menangkap semua error di atas dengan benar, di Python:

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}")

Versi Node.js-nya:

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 di res.php: Gagal Saat Polling Hasil

Error ini muncul saat Anda polling https://ocr.captchaai.com/res.php untuk mengambil hasilnya. Task-nya sudah diterima; yang gagal adalah proses solve atau cara Anda mengambil hasilnya.

Daftar Kode Error res.php

Pola polling yang benar, di Python:

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]}...")

Versi Node.js-nya:

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

Kenapa Halaman Target Tetap Menolak Token yang Valid

Ini kegagalan paling menyebalkan untuk di-debug: API mengembalikan token valid, in.php dan res.php sama-sama melaporkan sukses, tapi form di halaman target tetap menolaknya.

Metode Inject dan Callback yang Tidak Sesuai

Sebagian halaman mencari token di textarea g-recaptcha-response. Yang lain memanggil grecaptcha.getResponse(). Yang lain lagi menunggu callback dipanggil langsung — mengisi field tersembunyi saja tidak cukup untuk kasus ini. Periksa halaman untuk menentukan jalur yang seharusnya dipakai:

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

Kalau widget punya data-callback="onSuccess" atau memakai grecaptcha.render() dengan properti callback, Anda harus memanggil fungsi callback-nya secara langsung, seperti ini:

// 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 Saat Disubmit

Kalau lebih dari ~2 menit berlalu antara token diterima dan form disubmit, Google menolaknya — lebih sering terjadi daripada kelihatannya di pipeline lintas region. Contoh: worker browser headless di Singapura (ap-southeast-1), staging di Jakarta (asia-southeast2) — round-trip saja menambah 150–300 ms, ditambah antrean queue browser, total jeda gampang tembus 2 menit. Submit form segera setelah menerima token; kalau pipeline lambat, minta solve lebih dekat ke langkah submit.

Widget Dimuat di Dalam iframe Domain Lain

Kalau reCAPTCHA dimuat di dalam iframe dari domain berbeda, pageurl yang harus Anda pakai adalah URL sumber iframe, bukan URL halaman induk. Error ERROR_BAD_TOKEN_OR_PAGEURL biasanya menandakan masalah ini — cari iframe yang memuat reCAPTCHA, lalu pakai URL src-nya sebagai pageurl.

Pertanyaan Umum seputar Error reCAPTCHA v2

CAPCHA_NOT_READY itu tanda error atau normal?

Normal — bukan error. Kode ini muncul saat Anda polling res.php sementara CaptchaAI masih memproses solve-nya. Tunggu 5 detik, lalu polling lagi. Waktu solve reCAPTCHA v2 standar umumnya 15–60 detik; kalau CAPCHA_NOT_READY masih muncul setelah 3 menit, naikkan timeout ke 180 detik dulu sebelum menganggapnya gagal.

ERROR_CAPTCHA_UNSOLVABLE terus muncul, salahnya di mana?

Jangan retry task ID yang sama — kirim task baru dengan parameter segar.

Kalau errornya berulang di banyak task berbeda, penyebab paling sering adalah googlekey atau pageurl yang salah, atau CAPTCHA di halaman itu sebenarnya reCAPTCHA v2 Enterprise, bukan reCAPTCHA v2 standar.

Apa bedanya error in.php, res.php, dan reCAPTCHA v2 Enterprise?

Tiga kebingungan yang paling sering muncul:

• in.php vs res.php — error in.php berarti task ditolak sebelum sempat diproses, perbaikannya ada di kode pengiriman Anda; error res.php muncul saat Anda mengambil hasil dari task yang sudah sempat diproses tapi gagal di tengah jalan, atau ID yang dipolling tidak valid.
• reCAPTCHA v2 Enterprise — lazim dipakai di portal perbankan atau instansi pemerintah, dan membutuhkan parameter tambahan di luar googlekey dan pageurl. Cek apakah widget memuat skrip recaptcha/enterprise.js sebelum menyalahkan googlekey.
• Pola errornya sendiri — sama-sama memakai kode error di atas; yang berbeda hanya parameter tambahan yang wajib disertakan untuk Enterprise.

Berapa thread yang idealnya dipakai supaya retry paralel tidak saling tabrakan?

Jumlah task simultan (termasuk retry) sebaiknya tidak melebihi thread aktif di paket Anda:

• BASIC ($15/bulan, 5 thread) — solve tanpa batas per thread; retry tidak menambah biaya per solve, hanya menambah antrean kalau semua thread terpakai.
• STANDARD ($30/bulan, 15 thread) atau ADVANCE ($90/bulan, 50 thread) — cocok untuk volume scraping harian yang lebih besar, memberi ruang retry paralel tanpa task saling menunggu.

Langkah Perbaikan reCAPTCHA v2 dalam 4 Tahap

Mulai selesaikan reCAPTCHA v2 dengan CaptchaAI — ambil API key Anda di captchaai.com/api.php dan uji ulang task yang tadinya gagal.

Panduan Terkait

Pendalaman lebih lanjut: Cara Solve reCAPTCHA v2 dengan API untuk tutorial lengkap langkah demi langkah, Cara Solve Callback reCAPTCHA v2 dengan API untuk penanganan callback secara khusus, dan Referensi Kode Error CaptchaAI untuk daftar lengkap semua kode error.