Kode Error CaptchaAI: Referensi Lengkap dan Perbaikan

Kegagalan request ke CaptchaAI API hampir tidak pernah acak. Setiap respons gagal membawa satu kode error yang secara eksplisit memberi tahu langkah berikutnya: perbaiki request, tunggu lalu coba ulang, atau cukup lanjutkan polling. Begitu Anda bisa membaca kode itu, sebagian besar "bug" ternyata hanya instruksi.

Halaman ini memetakan seluruh kode error CaptchaAI per endpoint, lengkap dengan penyebab dan perbaikannya. CaptchaAI API bekerja lewat dua endpoint, dan kode error menunjukkan di tahap mana request gagal: in.php tempat Anda submit task (error muncul saat pengiriman) dan res.php tempat Anda polling hasil (error muncul saat pengambilan hasil).

Dengan menyertakan json=1, error dikembalikan dalam bentuk JSON; tanpa json=1, error dikembalikan sebagai teks biasa ERROR_CODE_HERE:

{"status": 0, "request": "ERROR_CODE_HERE"}

Peta cepat semua kode error CaptchaAI

Jika Anda hanya ingin tahu satu hal — retry atau tidak — mulai dari tabel ini.

Triase cepat: tiga aturan untuk 90% kasus

Kuncinya bukan menghafal tiap kode, melainkan mengenali kelasnya. Tiga aturan berikut menutup hampir semua kasus yang Anda temui di produksi.

Aturan sederhananya: error parameter menuntut perbaikan kode, error server menuntut kesabaran, dan CAPCHA_NOT_READY bukan error sama sekali.

Error saat submit task (in.php)

Error di bawah ini muncul ketika Anda mengirim task CAPTCHA baru.

ERROR_WRONG_USER_KEY

Penyebab: Parameter key formatnya salah. API key CaptchaAI terdiri dari 32 karakter. Periksa apakah key Anda tepat 32 karakter, tidak ada spasi tambahan atau baris baru yang ikut tersalin, dan disalin langsung dari dashboard API CaptchaAI.

{
  "key": "abc123... "
}

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

Penyebab: API key tidak cocok dengan akun mana pun di sistem. Login ke captchaai.com, salin key dari dashboard Anda, dan pastikan Anda memakai key dari akun yang benar. Jika akun baru saja dibuat, tunggu beberapa menit hingga key aktif.

ERROR_ZERO_BALANCE

Penyebab: Akun Anda tidak punya thread yang tersedia untuk menerima task. Tunggu hingga task yang sedang berjalan selesai (thread akan kembali kosong), upgrade paket agar mendapat lebih banyak thread concurrent, atau cek saldo di dashboard API CaptchaAI.

Ini tidak selalu berarti saldo habis. Sering kali artinya semua thread pada paket Anda sedang terpakai. Contoh: pada paket BASIC ($15/bulan, 5 thread), begitu kelima thread sibuk, submit berikutnya akan mengembalikan error ini sampai salah satu task selesai dan thread-nya bebas kembali.

ERROR_PAGEURL

Penyebab: Parameter pageurl tidak ada atau kosong. Parameter ini wajib untuk CAPTCHA berbasis token (reCAPTCHA, Cloudflare Turnstile, GeeTest, dll.).

Perbaikan: Isi dengan URL lengkap halaman tempat CAPTCHA dimuat, termasuk protokolnya:

{
  "pageurl": ""
}

{
  "pageurl": "https://staging.example.com/qa-login"
}

ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY

Penyebab: Parameter googlekey (sitekey) kosong, formatnya salah, atau tidak ada.

Perbaikan: Ekstrak ulang sitekey dari atribut data-sitekey di halaman target atau dari parameter k pada URL anchor reCAPTCHA, lalu pastikan nilainya tidak kosong atau terpotong.

{
  "googlekey": ""
}

{
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}

ERROR_BAD_TOKEN_OR_PAGEURL

Penyebab: Kombinasi googlekey (sitekey) dan pageurl tidak valid — sitekey tidak terdaftar untuk URL halaman yang Anda berikan. Ini biasanya terjadi karena widget reCAPTCHA dimuat dalam iframe pada subdomain berbeda sementara Anda memakai URL halaman induk, karena sitekey milik halaman/domain lain, atau karena sitekey diambil dari environment staging alih-alih produksi.

Perbaikan:

1. Jika reCAPTCHA ada di iframe, pakai URL src iframe sebagai pageurl.
2. Verifikasi sitekey langsung dari halaman produksi.
3. Uji kedua nilai dengan memuat URL anchor reCAPTCHA secara manual: https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY

Error unggahan gambar

Untuk CAPTCHA gambar/normal, lima kode berikut semuanya soal file yang Anda kirim. Perlakuannya sama: perbaiki gambar lebih dulu, jangan retry payload yang sama.

ERROR_BAD_PROXY

Penyebab: Proxy yang Anda berikan tidak dapat dijangkau atau sudah ditandai buruk oleh sistem.

Perbaikan:

1. Uji proxy secara terpisah — apakah ia bisa terhubung ke situs target?
2. Coba proxy lain.
3. Periksa formatnya: login:password@IP:PORT atau IP:PORT untuk proxy yang diautentikasi via IP.

Penggunaan proxy harus diaktifkan lebih dulu di akun Anda. Hubungi support CaptchaAI jika belum melakukannya.

ERROR_BAD_PARAMETERS

Penyebab: Parameter wajib tidak ada atau tipe datanya salah.

Perbaikan: Cek dokumentasi API untuk jenis CAPTCHA yang sedang Anda selesaikan, lalu pastikan semua parameter wajib sudah terkirim:

IP_BANNED

Penyebab: IP Anda diblokir sementara setelah beberapa kali gagal autentikasi berturut-turut.

Perbaikan: Tunggu sekitar 5 menit, lalu coba lagi dengan kredensial yang benar. Jangan terus mengirim request dengan API key yang salah — itu justru memperpanjang blokir.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

Penyebab: Terjadi kesalahan sementara di sisi server.

Perbaikan: Tunggu 10 detik lalu coba lagi. Gunakan exponential backoff (jeda yang meningkat eksponensial) untuk kegagalan beruntun:

import time

retry_delay = 10
for attempt in range(5):
    response = submit_captcha()
    if response.get("status") == 1:
        break
    time.sleep(retry_delay)
    retry_delay *= 2  # 10s, 20s, 40s, 80s, 160s

Error saat polling hasil (res.php)

Error di bawah ini muncul ketika Anda memeriksa status task yang sudah disubmit.

CAPCHA_NOT_READY

Ini bukan error. Artinya proses penyelesaian masih berjalan. Tunggu 5 detik lalu polling lagi:

if result.get("request") == "CAPCHA_NOT_READY":
    time.sleep(5)
    continue  # poll again

Kapan mulai polling dan seberapa sering bergantung pada jenis CAPTCHA:

ERROR_CAPTCHA_UNSOLVABLE

Penyebab: CaptchaAI tidak berhasil menyelesaikan CAPTCHA setelah beberapa kali percobaan. Penyebab umumnya: jenis CAPTCHA tidak didukung atau parameternya salah, challenge rusak/kedaluwarsa, proxy terlalu lambat pada penyelesaian berbasis proxy, atau situs telah mengubah implementasi CAPTCHA-nya.

Perbaikan:

1. Verifikasi parameter Anda (sitekey, pageurl, method) sudah benar.
2. Submit ulang sebagai request baru.
3. Jika memakai proxy, coba proxy lain.
4. Jika error berulang, kemungkinan situs sudah berubah — ekstrak ulang sitekey dan pageurl.

Jangan retry ID task yang sama. Kirim task baru dengan parameter baru.

ERROR_EMPTY_ACTION

Penyebab: Parameter action tidak ada atau kosong pada request polling Anda.

Perbaikan: Tambahkan action=get ke request res.php Anda:

params = {
    "key": api_key,
    "action": "get",  # Required
    "id": captcha_id,
    "json": 1,
}

ERROR_PROXY_CONNECTION_FAILED

Penyebab: Solver tidak bisa terhubung ke situs target lewat proxy Anda.

Perbaikan: Proxy mungkin sedang down sementara, atau situs target memblokir IP proxy tersebut. Coba proxy lain dan pastikan proxy memang mampu menjangkau situs target.

Error ID task tidak valid

Dua kode berikut sama-sama menandakan ID yang Anda pakai untuk polling bermasalah:

Selain itu, ERROR_WRONG_USER_KEY dan ERROR_KEY_DOES_NOT_EXIST juga bisa muncul di res.php — penyebab dan perbaikannya sama seperti pada error submit di atas.

Template penanganan error siap pakai

Salin pola berikut untuk penanganan error yang tahan banting, di bahasa apa pun. Intinya: pisahkan error yang harus diperbaiki dari error yang boleh di-retry, lalu terapkan backoff.

Python

import time
import requests

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

# Errors that should not be retried (fix the request first)
NO_RETRY_ERRORS = {
    "ERROR_WRONG_USER_KEY",
    "ERROR_KEY_DOES_NOT_EXIST",
    "ERROR_PAGEURL",
    "ERROR_WRONG_GOOGLEKEY",
    "ERROR_GOOGLEKEY",
    "ERROR_BAD_TOKEN_OR_PAGEURL",
    "ERROR_BAD_PARAMETERS",
    "ERROR_WRONG_FILE_EXTENSION",
    "ERROR_IMAGE_TYPE_NOT_SUPPORTED",
    "IP_BANNED",
}

# Errors that can be retried
RETRY_ERRORS = {
    "ERROR_ZERO_BALANCE",
    "ERROR_SERVER_ERROR",
    "ERROR_INTERNAL_SERVER_ERROR",
    "ERROR_UPLOAD",
}


def solve_captcha(submit_data, max_retries=3, max_polls=60):
    """Submit and solve a CAPTCHA with full error handling."""

    # Submit with retry logic
    for attempt in range(max_retries):
        resp = requests.post(SUBMIT_URL, data={**submit_data, "json": 1}, timeout=30)
        resp.raise_for_status()
        data = resp.json()

        if data.get("status") == 1:
            captcha_id = data["request"]
            break

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

        if error in NO_RETRY_ERRORS:
            raise ValueError(f"Fatal error (fix request): {error}")

        if error in RETRY_ERRORS and attempt < max_retries - 1:
            time.sleep(10 * (2 ** attempt))
            continue

        raise RuntimeError(f"Submit failed: {error}")
    else:
        raise RuntimeError("Submit failed after max retries")

    # Poll for result
    time.sleep(15)

    for _ in range(max_polls):
        resp = requests.get(
            RESULT_URL,
            params={"key": API_KEY, "action": "get", "id": captcha_id, "json": 1},
            timeout=30,
        )
        data = resp.json()

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

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

        error = data.get("request", "UNKNOWN")
        if error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable — resubmit with fresh parameters")

        raise RuntimeError(f"Poll error: {error}")

    raise TimeoutError("Solve timed out")

Node.js

const NO_RETRY_ERRORS = new Set([
  "ERROR_WRONG_USER_KEY",
  "ERROR_KEY_DOES_NOT_EXIST",
  "ERROR_PAGEURL",
  "ERROR_WRONG_GOOGLEKEY",
  "ERROR_BAD_TOKEN_OR_PAGEURL",
  "ERROR_BAD_PARAMETERS",
  "IP_BANNED",
]);

async function solveCaptcha(submitData, maxRetries = 3, maxPolls = 60) {
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

  // Submit with retry
  let captchaId;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch("https://ocr.captchaai.com/in.php", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ ...submitData, json: "1" }),
    });
    const data = await resp.json();

    if (data.status === 1) {
      captchaId = data.request;
      break;
    }

    if (NO_RETRY_ERRORS.has(data.request)) {
      throw new Error(`Fatal error: ${data.request}`);
    }

    if (attempt < maxRetries - 1) {
      await sleep(10_000 * 2 ** attempt);
      continue;
    }

    throw new Error(`Submit failed: ${data.request}`);
  }

  // Poll for result
  await sleep(15_000);

  for (let i = 0; i < maxPolls; i++) {
    const resp = await fetch(
      `https://ocr.captchaai.com/res.php?${new URLSearchParams({
        key: submitData.key,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );
    const data = await resp.json();

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

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

    throw new Error(`Poll error: ${data.request}`);
  }

  throw new Error("Solve timed out");
}

Pertanyaan umum

Apakah CAPCHA_NOT_READY termasuk error?

Bukan. Artinya proses penyelesaian masih berjalan. Tunggu 5 detik lalu polling lagi. Respons ini normal untuk setiap jenis CAPTCHA dan bukan tanda ada yang salah.

Kenapa saya kena ERROR_ZERO_BALANCE padahal saldo masih ada?

Karena error ini soal thread, bukan uang. Selama semua thread pada paket Anda sedang memproses task, submit baru akan ditolak sampai salah satu thread bebas. Tunggu task berjalan selesai, atau naik ke paket dengan thread concurrent lebih banyak.

Berapa jeda ideal sebelum mencoba ulang request yang gagal?

Untuk error server, mulai dari 10 detik lalu gandakan tiap percobaan (10s, 20s, 40s). Untuk CAPCHA_NOT_READY, cukup 5 detik. Jika Anda deploy jauh dari server — misalnya region ap-southeast-1 (Singapura) atau ap-southeast-3 (Jakarta) — perhitungkan sedikit latency ekstra pada batas timeout Anda.

Bagaimana membedakan error yang perlu diperbaiki dan yang cukup di-retry?

Error parameter/format (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, dll.) tidak boleh di-retry — perbaiki dulu request-nya. Error server (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) aman di-retry dengan exponential backoff. ERROR_ZERO_BALANCE bisa dicoba ulang setelah thread kosong.

Paket CaptchaAI mana yang menekan ERROR_ZERO_BALANCE saat volume tinggi?

Karena penagihan berbasis thread concurrent (bukan per solve), naikkan jumlah thread agar lebih banyak task berjalan paralel. Dari BASIC ($15/bulan, 5 thread) ke STANDARD ($30/bulan, 15 thread) atau ADVANCE ($90/bulan, 50 thread), makin banyak thread makin jarang submit tertahan.

Panduan terkait

• Panduan memulai CaptchaAI — sukseskan penyelesaian pertama Anda
• Cara menyelesaikan reCAPTCHA v2 lewat API — tutorial lengkap reCAPTCHA v2
• Menyelesaikan Cloudflare Challenge yang butuh proxy — alur khusus Cloudflare Challenge
• Error umum saat menyelesaikan reCAPTCHA v2 — troubleshooting spesifik reCAPTCHA