Kesalahan dan Perbaikan Umum GeeTest v3

Kalau integrasi GeeTest v3 Anda gagal padahal gt dan pageurl sudah benar, curigai satu hal lebih dulu: nilai challenge yang basi. Ini akar dari sebagian besar kegagalan GeeTest yang dilaporkan tim automation — bukan bug di API CaptchaAI, melainkan challenge yang ditangkap sekali lalu dipakai ulang di beberapa request solve.

Dokumentasi resmi GeeTest v3 CaptchaAI tegas soal ini: setiap request solve butuh nilai challenge baru. Begitu widget GeeTest dimuat ulang di halaman, challenge lama otomatis tidak valid — jadi request Anda bisa gagal meski parameter lain terlihat sudah tepat.

Panduan ini memetakan tiga kelompok kegagalan GeeTest v3 — submit ke in.php, polling res.php, dan validasi di halaman target — lengkap dengan perbaikan konkret untuk masing-masing.

Tabel Referensi Cepat: Error GeeTest v3 dan Solusinya

Cari error Anda di tabel ini dulu, lalu lompat ke bagian detail untuk penjelasan lengkap.

Kalau error Anda tidak ada di tabel ini, atau solusi cepatnya belum menyelesaikan masalah, lanjut ke akar masalah paling umum di bawah.

Akar Masalah Nomor Satu: Challenge GeeTest v3 yang Basi

Kalau ada satu hal yang perlu Anda periksa lebih dulu sebelum menelusuri tabel di atas, itu adalah kesegaran challenge.

GeeTest v3 memerlukan dua parameter utama:

• gt — sitekey publik (statis, tidak berubah)
• challenge — kunci challenge dinamis (berubah setiap page load)

Kenapa Ini Terjadi

Nilai challenge dihasilkan saat widget GeeTest diinisialisasi di halaman. Kalau Anda menangkapnya sekali lalu memakainya ulang di beberapa request solve, setiap request setelah yang pertama akan:

• ditolak API CaptchaAI saat submit, atau
• menghasilkan nilai yang ditolak halaman target karena challenge sudah kedaluwarsa

Cara Memastikan Challenge Selalu Fresh

Sebelum setiap request solve, periksa network request halaman untuk menemukan API call yang mengembalikan challenge baru. Replay request itu untuk mendapatkan nilai baru, lalu langsung kirim ke CaptchaAI — jangan ditunda.

# Pseudocode: fetch a fresh challenge before each solve
import requests

def get_fresh_challenge(target_url):
    """Hit the GeeTest init endpoint to get a new challenge."""
    resp = requests.get(f"{target_url}/geetest/register", timeout=10)
    data = resp.json()
    return data["challenge"], data["gt"]

challenge, gt = get_fresh_challenge("https://example.com")
# Now submit to CaptchaAI immediately — do not delay

Aturan praktis: Kalau jeda antara menangkap challenge dan mengirim request solve lebih dari beberapa detik, ambil ulang dulu.

Skenario yang sering terjadi: tim QA di agensi price-monitoring Jakarta menjalankan job scraping terjadwal dari worker di region ap-southeast-3, lalu heran kenapa GeeTest v3 tiba-tiba menolak separuh task setelah retry otomatis jalan. Setelah ditelusuri, penyebabnya sederhana — retry logic mereka menyimpan challenge dari percobaan pertama dan memakainya ulang di percobaan kedua, alih-alih mengambil challenge baru setiap kali retry. Begitu retry logic diperbaiki agar selalu memanggil ulang endpoint geetest/register sebelum tiap percobaan, ERROR_CAPTCHA_UNSOLVABLE langsung hilang dari log.

Error GeeTest v3 Saat Submit ke in.php

Kegagalan ini muncul saat Anda mengirim task ke https://ocr.captchaai.com/in.php.

ERROR_WRONG_USER_KEY

Penyebab: Format API key salah — seharusnya 32 karakter. Solusi: Verifikasi key Anda di captchaai.com/api.php. Jangan tambahkan karakter atau spasi ekstra.

ERROR_KEY_DOES_NOT_EXIST

Penyebab: Format API key sudah benar, tapi tidak cocok dengan akun aktif mana pun. Solusi: Login ke dashboard CaptchaAI dan pastikan key Anda masih aktif.

ERROR_ZERO_BALANCE

Penyebab: Tidak ada thread kosong di paket Anda saat ini. Solusi: Tunggu thread kosong, kurangi concurrency, atau upgrade paket.

ERROR_PAGEURL

Penyebab: Parameter pageurl tidak disertakan dalam request. Solusi: Tambahkan URL lengkap halaman tempat widget GeeTest dimuat. Contoh:

pageurl=https://staging.example.com/qa-login

ERROR_BAD_PARAMETERS

Penyebab: Satu atau beberapa field wajib tidak ada atau salah format. Untuk GeeTest, parameter yang diperlukan:

Solusi: Periksa apakah gt, challenge, dan pageurl semuanya ada dan diformat dengan benar.

Respons HTML atau 500/502

Penyebab: Error sementara di sisi server — bukan masalah parameter. Solusi: Tunggu 5–10 detik, lalu coba lagi request tersebut.

Error GeeTest v3 Saat Polling res.php

Kegagalan ini muncul saat Anda polling https://ocr.captchaai.com/res.php.

CAPCHA_NOT_READY

Ini bukan error. Artinya captcha masih dalam proses solve — solve GeeTest v3 di CaptchaAI biasanya membutuhkan waktu di bawah 12 detik dengan tingkat keberhasilan tinggi pada tipe yang didukung. Solusi: tunggu 5 detik, lalu polling lagi; jangan anggap ini sebagai kegagalan.

ERROR_WRONG_ID_FORMAT

Penyebab: Format ID captcha salah — ID harus berupa angka saja. Solusi: Pastikan Anda memakai ID persis yang dikembalikan in.php, tanpa modifikasi.

ERROR_WRONG_CAPTCHA_ID

Penyebab: ID tidak cocok dengan task yang disubmit. Solusi: Periksa apakah Anda memakai ID yang benar dari respons submit. Kalau Anda mengirim beberapa task sekaligus, pastikan Anda melacak task yang tepat.

ERROR_EMPTY_ACTION

Penyebab: Parameter action tidak ada atau kosong di request polling Anda. Solusi: Sertakan action=get di setiap request polling:

https://ocr.captchaai.com/res.php?key=YOUR_KEY&action=get&id=CAPTCHA_ID

ERROR_CAPTCHA_UNSOLVABLE

Penyebab: Challenge tidak bisa di-solve — biasanya karena nilai challenge basi atau varian GeeTest yang tidak didukung. Solusi: Ambil ulang nilai challenge, lalu coba lagi.

ERROR_INTERNAL_SERVER_ERROR

Penyebab: Masalah di sisi server CaptchaAI. Solusi: Tunggu 10 detik, lalu coba lagi.

Kenapa Halaman Target Menolak Hasil GeeTest v3 yang Valid

Ini kegagalan paling sulit di-debug, karena API CaptchaAI sudah mengembalikan hasil yang valid, tapi halaman target tetap menolaknya.

Saat GeeTest v3 berhasil di-solve, API mengembalikan tiga nilai:

{
  "challenge": "1a2b3456cd67890e12345fab678901c2de",
  "validate": "09fe8d7c6ba54f32e1dcb0a9fedc8765",
  "seccode": "12fe3d4c56789ba01f2e345d6789c012|jordan"
}

Ketiganya harus disubmit ke halaman target sebagai:

Penyebab 1: Pemetaan Field Salah

Gejala: API mengembalikan nilai, tapi halaman target langsung menolaknya — penyebabnya, nilai yang dikembalikan dimasukkan ke field yang salah atau path request yang salah.

Solusi: Periksa network traffic dari solve GeeTest manual di halaman target. Temukan POST request yang mengirim hasil GeeTest, lalu cocokkan nama field Anda persis.

Penyebab 2: Challenge Basi di Upstream

Gejala: API mengembalikan nilai, tapi halaman menyatakan challenge sudah kedaluwarsa atau tidak valid — biasanya karena nilai challenge diambil terlalu awal atau dipakai ulang.

Solusi: Ambil challenge baru tepat sebelum setiap request solve. Jangan cache atau pakai ulang.

Penyebab 3: Konteks Halaman Salah

Gejala: Validasi tetap gagal meski inputnya sudah baru — pageurl yang dikirim ke CaptchaAI tidak cocok dengan halaman sebenarnya tempat widget GeeTest dimuat.

Solusi: Gunakan URL yang tepat, termasuk protokol dan path. Kalau widget dimuat via AJAX di route berbeda, gunakan URL route tersebut.

Penyebab 4: Struktur Request Tidak Cocok

Gejala: Field sudah benar, tapi format request salah — halaman target mengharapkan field GeeTest dalam content type tertentu (misalnya JSON body vs. form-encoded) atau bersama field form lain.

Solusi: Bandingkan request submit Anda dengan network traffic dari solve manual. Cocokkan content type, urutan field, dan field tambahan lainnya.

Diagnosis Cepat: 3 Hal yang Perlu Anda Pastikan Dulu

Sebelum menelusuri kode error satu per satu, cek tiga hal ini — kombinasinya menyelesaikan sebagian besar kasus GeeTest v3 tanpa perlu debugging panjang:

1. Challenge diambil ulang setiap percobaan — bukan dari cache, variabel global, atau hasil retry sebelumnya.
2. pageurl cocok persis dengan halaman tempat widget GeeTest benar-benar dimuat, termasuk protokol dan path — bukan domain root atau halaman redirect.
3. Field respons dipetakan ke nama yang tepat di sisi halaman target: challenge menjadi geetest_challenge, validate menjadi geetest_validate, seccode menjadi geetest_seccode.

Kalau ketiganya sudah benar dan error masih muncul, kembali ke tabel referensi cepat di atas untuk kode error yang spesifik.

Contoh Python: Solve GeeTest v3 dengan Challenge Baru

Contoh berikut menyatukan pengambilan challenge baru dan pola submit-polling menjadi satu fungsi siap pakai.

import time
import requests

API_KEY = "YOUR_CAPTCHAAI_API_KEY"

SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"


def get_fresh_challenge(target_url):
    """Fetch a fresh GeeTest challenge from the target page."""
    resp = requests.get(f"{target_url}/api/geetest/register", timeout=10)
    data = resp.json()
    return data["gt"], data["challenge"]


def solve_geetest_v3(api_key, gt, challenge, pageurl):
    """Submit a GeeTest v3 challenge and return the validation package."""

    # Submit
    submit_resp = requests.post(
        SUBMIT_URL,
        data={
            "key": api_key,
            "method": "geetest",
            "gt": gt,
            "challenge": challenge,
            "pageurl": pageurl,
            "json": 1,
        },
        timeout=30,
    )
    submit_resp.raise_for_status()
    submit_data = submit_resp.json()

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

    captcha_id = submit_data["request"]
    print(f"Task created — captcha ID: {captcha_id}")

    # Wait before first poll
    time.sleep(15)

    # Poll for result
    for _ in range(60):
        result_resp = requests.get(
            RESULT_URL,
            params={
                "key": api_key,
                "action": "get",
                "id": captcha_id,
                "json": 1,
            },
            timeout=30,
        )
        result_resp.raise_for_status()
        result_data = result_resp.json()

        if result_data.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result_data.get("status") == 1:
            return result_data["request"]

        raise RuntimeError(f"Polling error: {result_data}")

    raise TimeoutError("GeeTest v3 solve timed out")


# Usage: always fetch a fresh challenge first
PAGE_URL = "https://staging.example.com/qa-login"
gt, challenge = get_fresh_challenge(PAGE_URL)
result = solve_geetest_v3(API_KEY, gt, challenge, PAGE_URL)
print(f"Result: {result}")

# The result contains: challenge, validate, seccode
# Map them to: geetest_challenge, geetest_validate, geetest_seccode

Contoh Node.js: Solve GeeTest v3 dengan Challenge Baru

Struktur logikanya identik dengan versi Python — ambil challenge baru, submit, lalu polling sampai status siap.

const API_KEY = "YOUR_CAPTCHAAI_API_KEY";
const SUBMIT_URL = "https://ocr.captchaai.com/in.php";
const RESULT_URL = "https://ocr.captchaai.com/res.php";

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function getFreshChallenge(targetUrl) {
  const resp = await fetch(`${targetUrl}/api/geetest/register`);
  const data = await resp.json();
  return { gt: data.gt, challenge: data.challenge };
}

async function solveGeetestV3(apiKey, gt, challenge, pageurl) {
  // Submit
  const submitResp = await fetch(SUBMIT_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      key: apiKey,
      method: "geetest",
      gt: gt,
      challenge: challenge,
      pageurl: pageurl,
      json: "1",
    }),
  });

  const submitData = await submitResp.json();
  if (submitData.status !== 1) {
    throw new Error(`Submit failed: ${JSON.stringify(submitData)}`);
  }

  const captchaId = submitData.request;
  console.log(`Task created — captcha ID: ${captchaId}`);

  await sleep(15_000);

  // Poll for result
  for (let i = 0; i < 60; i++) {
    const resultResp = await fetch(
      `${RESULT_URL}?${new URLSearchParams({
        key: apiKey,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );

    const resultData = await resultResp.json();

    if (resultData.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }

    if (resultData.status === 1) {
      return resultData.request;
    }

    throw new Error(`Polling error: ${JSON.stringify(resultData)}`);
  }

  throw new Error("GeeTest v3 solve timed out");
}

// Usage
const PAGE_URL = "https://staging.example.com/qa-login";

(async () => {
  const { gt, challenge } = await getFreshChallenge(PAGE_URL);
  const result = await solveGeetestV3(API_KEY, gt, challenge, PAGE_URL);
  console.log("Result:", result);
  // Map result fields to: geetest_challenge, geetest_validate, geetest_seccode
})();

Pertanyaan Umum

Berapa thread CaptchaAI yang saya perlukan untuk debug GeeTest v3 secara paralel?

Satu thread menangani satu tantangan GeeTest v3 yang sedang berjalan. Untuk sesi debugging dan pengujian rutin, paket BASIC ($15/bulan, 5 thread) biasanya cukup — Anda bisa menjalankan beberapa percobaan solve sekaligus tanpa antre. Kalau volume pengujian naik atau Anda menjalankan beberapa worker paralel dari region berbeda (misalnya ap-southeast-1 dan ap-southeast-3), pertimbangkan STANDARD ($30/bulan, 15 thread) atau ADVANCE ($90/bulan, 50 thread).

Apa itu CAPCHA_NOT_READY dan haruskah saya khawatir?

Tidak. CAPCHA_NOT_READY bukan error — artinya solve GeeTest v3 masih diproses. Tunggu 5 detik, lalu polling res.php lagi. Solve GeeTest v3 di CaptchaAI biasanya membutuhkan waktu di bawah 12 detik dengan tingkat keberhasilan tinggi pada tipe yang didukung.

Apakah aman melakukan retry otomatis saat error GeeTest v3 muncul?

Ya, retry dengan jeda (backoff) adalah praktik normal untuk error sementara seperti respons HTML/500/502 atau ERROR_INTERNAL_SERVER_ERROR. Yang tidak boleh Anda lakukan adalah retry dengan challenge lama — itu penyebab paling umum kegagalan berulang. Selalu ambil challenge baru setiap kali Anda mengulang request solve, bukan hanya di percobaan pertama.

Bagaimana status GeeTest v4 di CaptchaAI?

Belum. Artikel ini membahas GeeTest v3, yang didukung penuh. Dukungan GeeTest v4 berstatus segera hadir — cek dokumentasi API CaptchaAI untuk daftar tipe CAPTCHA terbaru yang sudah didukung.

Bagaimana cara memastikan fix challenge basi sudah benar-benar berhasil sebelum deploy ke produksi?

Jalankan minimal 10–20 percobaan solve berturut-turut di lingkungan staging dengan retry logic yang sudah diperbaiki, lalu periksa apakah semuanya mengambil challenge baru dan bukan hasil cache. Kalau tidak ada lagi ERROR_CAPTCHA_UNSOLVABLE atau penolakan di halaman target selama percobaan itu, fix Anda aman untuk di-deploy.

Checklist Perbaikan GeeTest v3 Anda

Kalau integrasi GeeTest v3 Anda masih gagal, telusuri urutan ini:

1. Cek kesegaran challenge — Apakah diambil segera sebelum solve, bukan dari cache atau percobaan sebelumnya?
2. Verifikasi parameter — gt, challenge, dan pageurl semuanya benar dan lengkap?
3. Cocokkan pemetaan field — challenge, validate, seccode dari respons masuk ke geetest_challenge, geetest_validate, geetest_seccode yang tepat?
4. Bandingkan dengan solve manual — Tangkap struktur request persis dari solve GeeTest manual yang berhasil lewat DevTools browser.

Kalau alur ini bagian dari pekerjaan scraping, batasi diri pada data yang memang berhak Anda proses — sejalan dengan UU Pelindungan Data Pribadi (UU 27/2022).

Mulai dari GeeTest v3 Solver CaptchaAI, cocokkan parameter Anda dengan dokumentasi API, lalu ikuti panduan lengkap solve GeeTest v3 dengan API untuk implementasi dari nol. Kalau alur Anda juga menangani reCAPTCHA v2, baca panduan solve reCAPTCHA v2 lewat API.

Bacaan Lanjutan

• Cara solve GeeTest v3 dengan Node.js
• Praktik solve GeeTest v3 pakai Node.js dan CaptchaAI
• Kesalahan dan perbaikan CAPTCHA gambar grid yang umum