Pemecahan Masalah

Kode Error CaptchaAI: Referensi Lengkap dan Perbaikan

Cloudflare Turnstile Web Scraping
Oleh Tim CaptchaAI Indonesia
Diterbitkan pada May 10, 2026
Kode Error CaptchaAI: Referensi Lengkap dan Perbaikan
Gambar unggulan tidak tersedia

Halaman ini mendokumentasikan setiap kode error yang dapat dikembalikan oleh CaptchaAI API, dikelompokkan berdasarkan endpoint. Gunakan untuk mendiagnosis request yang gagal, menerapkan penanganan error yang tepat, dan menghindari kesalahan umum.

CaptchaAI API memiliki dua endpoint:

  • in.php — submit task CAPTCHA (error terjadi saat submit)
  • res.php — polling untuk hasil (error terjadi saat mengambil hasil)

Saat menyertakan json=1 dalam request, error dikembalikan sebagai JSON:

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

Tanpa json=1, error dikembalikan sebagai teks biasa: ERROR_CODE_HERE

Aturan Penanganan Error Cepat

Sebelum referensi lengkapnya, tiga aturan berikut menangani 90% kasus:

Pola error Tindakan
CAPCHA_NOT_READY Normal — polling lagi dalam 5 detik
ERROR_ yang berkaitan dengan parameter/format Perbaiki request Anda — jangan retry request yang sama
Error server (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) Retry setelah 10 detik dengan exponential backoff

Error Submit (in.php)

Error ini terjadi saat Anda submit task CAPTCHA baru.

ERROR_WRONG_USER_KEY

Penyebab: Parameter key memiliki format yang salah. API key CaptchaAI terdiri dari 32 karakter.

Perbaikan:

  1. Periksa apakah key Anda tepat 32 karakter.
  2. Pastikan tidak ada spasi tambahan atau baris baru.
  3. Salin key langsung dari captchaai.com/api.php.
{
  "key": "abc123... "
}

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

Penyebab: API key tidak cocok dengan akun mana pun di sistem.

Perbaikan:

  1. Login ke captchaai.com dan salin key dari dashboard Anda.
  2. Pastikan Anda menggunakan key akun yang benar.
  3. Jika baru saja membuat akun, tunggu beberapa menit hingga key diaktifkan.

ERROR_ZERO_BALANCE

Penyebab: Akun Anda tidak memiliki thread yang tersedia untuk menerima task.

Perbaikan:

  1. Tunggu hingga task yang sedang berjalan selesai (thread akan kosong).
  2. Upgrade paket Anda untuk thread concurrent yang lebih banyak.
  3. Cek saldo akun Anda di captchaai.com/api.php.

Ini tidak selalu berarti dana habis. Bisa juga berarti semua thread Anda sedang sibuk. Jika Anda memiliki paket single-thread dan satu task sedang berjalan, submit baru akan mengembalikan error ini hingga task pertama selesai.

ERROR_PAGEURL

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

Perbaikan: Tambahkan 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:

  1. Ekstrak ulang sitekey dari atribut data-sitekey halaman target atau parameter k di URL anchor reCAPTCHA.
  2. 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 diberikan.

Penyebab umum:

  • Widget reCAPTCHA dimuat di dalam iframe pada subdomain berbeda. Anda menggunakan URL halaman induk, bukan URL iframe.
  • Sitekey milik halaman atau domain berbeda.
  • Sitekey diekstrak dari environment development/staging.

Perbaikan:

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

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Penyebab: Gambar yang diunggah melebihi ukuran maksimum yang diperbolehkan.

Perbaikan: Kompres atau ubah ukuran gambar sebelum dikirim. Gunakan JPEG untuk foto, PNG untuk tangkapan layar.

ERROR_ZERO_CAPTCHA_FILESIZE

Penyebab: File gambar terlalu kecil (kurang dari 100 byte), menandakan unggahan kosong atau rusak.

Perbaikan: Pastikan Anda mengirimkan data gambar sebenarnya, bukan file kosong atau string base64 yang rusak.

ERROR_WRONG_FILE_EXTENSION

Penyebab: File yang diunggah memiliki ekstensi yang tidak didukung. Didukung: jpg, jpeg, png, gif.

Perbaikan: Konversikan gambar ke format yang didukung sebelum diunggah.

ERROR_IMAGE_TYPE_NOT_SUPPORTED

Penyebab: Server tidak dapat menentukan jenis gambar dari konten file.

Perbaikan: Konversikan ke format standar (PNG atau JPEG) dan pastikan file tidak rusak.

ERROR_UPLOAD

Penyebab: Server tidak dapat membaca file yang diunggah atau payload base64.

Perbaikan:

  1. Untuk unggahan file: verifikasi pengkodean data formulir multi-bagian Anda.
  2. Untuk base64: verifikasi string base64 sudah lengkap dan dikodekan dengan benar.
  3. Uji dengan gambar yang dikenal bagus untuk menyingkirkan kerusakan file.

ERROR_BAD_PROXY

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

Perbaikan:

  1. Uji proxy secara independen — bisakah proxy terhubung ke situs target?
  2. Coba proxy lain.
  3. Verifikasi format: login:password@IP:PORT atau IP:PORT untuk proxy yang diautentikasi IP.

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

ERROR_BAD_PARAMETERS

Penyebab: Parameter yang diperlukan tidak ada atau jenis datanya salah.

Perbaikan: Periksa dokumentasi API untuk jenis CAPTCHA spesifik yang Anda pecahkan dan verifikasi semua parameter yang diperlukan ada:

Jenis CAPTCHA Parameter yang Diperlukan
reCAPTCHA v2/v3 key, method=userrecaptcha, googlekey, pageurl
Cloudflare Turnstile key, method=turnstile, sitekey, pageurl
Cloudflare Challenge key, method=cloudflare_challenge, pageurl, proxy, proxytype
GeeTest v3 key, method=geetest, gt, challenge, pageurl
BL key, method=bls, body, textinstructions
Normal/image key, method=post, file atau body

IP_BANNED

Penyebab: IP Anda telah diblokir sementara setelah upaya autentikasi gagal yang berulang.

Perbaikan: Tunggu sekitar 5 menit, lalu coba lagi dengan kredensial yang benar. Jangan terus-menerus mengirimkan request dengan API key yang salah.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

Penyebab: Terjadi kesalahan sementara di sisi server.

Perbaikan: Tunggu 10 detik dan coba lagi. Gunakan backoff eksponensial untuk kegagalan berulang:

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 Polling (res.php)

Error ini terjadi saat Anda memeriksa status task yang sudah disubmit.

CAPCHA_NOT_READY

Ini bukan kesalahan. Artinya penyelesaian masih dalam proses.

Tindakan: Tunggu 5 detik dan lakukan polling lagi.

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

Panduan waktu: | Jenis CAPTCHA | Poll pertama setelah | Interval poll | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 detik | 5 detik | | Cloudflare Turnstile | 15 detik | 5 detik | | Cloudflare Challenge | 20 detik | 5 detik | | GeeTest v3 | 15 detik | 5 detik | | Normal/image CAPTCHA | 5 detik | 5 detik |

ERROR_CAPTCHA_UNSOLVABLE

Penyebab: CaptchaAI tidak dapat menyelesaikan CAPTCHA setelah beberapa kali mencoba.

Alasan umum:

  1. Jenis CAPTCHA tidak didukung atau parameternya salah.
  2. Challenge rusak atau sudah kedaluarsa.
  3. Untuk solve berbasis proxy: proxy terlalu lambat atau tidak bisa dijangkau.
  4. Situs telah mengubah implementasi CAPTCHA-nya.

Perbaikan:

  1. Verifikasi parameter Anda (sitekey, pageurl, method) sudah benar.
  2. Submit ulang dengan request baru.
  3. Jika menggunakan proxy, coba yang lain.
  4. Jika error berulang, situs mungkin telah berubah — ekstrak ulang sitekey dan pageurl.

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

ERROR_WRONG_ID_FORMAT

Penyebab: ID CAPTCHA harus berupa angka saja.

Perbaikan: Pastikan Anda mengirimkan ID persis yang dikembalikan oleh in.php (hanya digit, tanpa karakter tambahan).

ERROR_WRONG_CAPTCHA_ID

Penyebab: ID task tidak ada atau sudah kedaluarsa.

Perbaikan:

  1. Verifikasi bahwa Anda polling dengan ID yang dikembalikan oleh submit Anda.
  2. ID task mungkin kedaluarsa setelah jangka waktu yang lama — submit ulang jika task sudah sangat lama.

ERROR_EMPTY_ACTION

Penyebab: Parameter action tidak ada atau kosong dalam 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 dapat terhubung ke situs target melalui proxy Anda.

Perbaikan:

  1. Proxy mungkin sedang down sementara — coba yang lain.
  2. Situs target mungkin memblokir IP proxy.
  3. Pastikan proxy benar-benar bisa menjangkau situs target.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

Ini juga dapat muncul di res.php — penyebab dan perbaikan yang sama seperti kesalahan pengiriman di atas.

Template Penanganan Error

Salin pola ini untuk penanganan error yang kuat dalam bahasa apa pun:

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 sebuah error?

Tidak. Artinya solve masih dalam proses. Tunggu 5 detik dan polling lagi. Ini normal untuk setiap jenis CAPTCHA.

Apa yang harus dilakukan saat mendapat ERROR_CAPTCHA_UNSOLVABLE?

Submit task baru dengan parameter baru. Jangan retry ID task yang sama. Jika error berulang, verifikasi sitekey dan pageurl Anda sudah benar dan jenis CAPTCHA didukung.

Bagaimana cara tahu apakah error bisa di-retry?

Error parameter/format (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, dll.) tidak bisa di-retry — perbaiki request terlebih dahulu. Error server (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) bisa di-retry dengan exponential backoff. ERROR_ZERO_BALANCE bisa di-retry setelah menunggu thread kosong.

Mengapa saya mendapat ERROR_BAD_PROXY untuk Cloudflare Challenge?

Cloudflare Challenge memerlukan proxy yang berfungsi. Proxy harus bisa menjangkau situs target. Uji secara independen, lalu coba proxy lain jika gagal. Pastikan juga penggunaan proxy diaktifkan di akun CaptchaAI Anda.

Di mana saya bisa menemukan API key saya?

Login ke captchaai.com dan pergi ke captchaai.com/api.php. API key 32 karakter Anda ditampilkan di dashboard.

Panduan Terkait

  • Panduan Memulai CaptchaAI — buat solve pertama Anda berhasil
  • Cara Solve reCAPTCHA v2 Menggunakan API — tutorial lengkap reCAPTCHA v2
  • Cara Solve Cloudflare Challenge Menggunakan API — solve Cloudflare yang memerlukan proxy
  • Error Umum Solve reCAPTCHA v2 — troubleshooting spesifik reCAPTCHA
Komentar dinonaktifkan untuk artikel ini.