Sorun Giderme

CaptchaAI Hata Kodları: Tam Referans ve Düzeltmeler

Cloudflare Turnstile Web Scraping
Yazan CaptchaAI Türkçe Ekibi
Yayınlanma tarihi May 11, 2026
CaptchaAI Hata Kodları: Tam Referans ve Düzeltmeler
Öne çıkan görsel mevcut değil

Bu sayfa, CaptchaAI API'nin döndürebileceği her hata kodunu uç noktaya göre düzenlenmiş olarak belgelemektedir. Başarısız istekleri teşhis etmek, doğru hata işlemeyi uygulamak ve yaygın hatalardan tanılamak için bunu kullanın.

CaptchaAI API'sinin iki uç noktası vardır:

  • in.php — bir CAPTCHA görevi gönderin (gönderim sırasında hatalar oluşur)
  • res.php — sonuç için anket (sonuçlar alınırken hatalar meydana gelir)

İsteğinize json=1'yi eklediğinizde hatalar JSON olarak döndürülür:

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

json=1 olmadan hatalar düz metin olarak geri döner: ERROR_CODE_HERE

Hızlı hata işleme kuralları

Tam referanstan önce, vakaların %90'ını ele alan üç kural aşağıda verilmiştir:

Hata modeli Eylem
CAPCHA_NOT_READY Normal — 5 saniye sonra tekrar anket yapın
/format parametresiyle başlayan herhangi bir ERROR_ sorunu İsteğinizi düzeltin; aynı isteği yeniden denemeyin
Sunucu hataları (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) Üstel geri çekilmeyle 10 saniye sonra yeniden deneyin

Hataları gönder (in.php)

Bu hatalar, yeni bir CAPTCHA görevi gönderdiğinizde ortaya çıkar.

ERROR_WRONG_USER_KEY

Neden: key parametresi yanlış formatta. CaptchaAI API anahtarları 32 karakterden oluşur.

Düzeltme:

  1. Anahtarınızın tam olarak 32 karakter olduğundan emin olun.
  2. Fazladan boşluk veya satır sonu olmadığından emin olun.
  3. Anahtarı doğrudan şuradan kopyalayın:captchaai.com/api.php.
{
  "key": "abc123... "
}

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

Neden: API anahtarı sistemdeki hiçbir hesapla eşleşmiyor.

Düzeltme:

  1. Giriş yapcaptchaai.comve anahtarı kontrol panelinizden kopyalayın.
  2. Doğru hesabın anahtarını kullandığınızdan emin olun.
  3. Hesabı yakın zamanda oluşturduysanız anahtarın etkinleştirilmesi için birkaç dakika bekleyin.

ERROR_ZERO_BALANCE

Neden: Hesabınızda görevi kabul etmek için kullanılabilir ileti dizisi yok.

Düzeltme:

  1. Şu anda çalışan görevlerin tamamlanmasını bekleyin (iş parçacıkları serbest kalacaktır).
  2. Daha fazla eş zamanlı iş parçacığı için planınızı yükseltin.
  3. Hesap bakiyenizi şu adresten kontrol edin:captchaai.com/api.php.

Bu her zaman fon yetersizliği hatası değildir. Bu aynı zamanda tüm konularınızın şu anda meşgul olduğu anlamına da gelebilir. Tek iş parçacıklı bir planınız varsa ve bir görev çalışıyorsa, yeni gönderimler ilk görev tamamlanana kadar bu hatayı döndürecektir.

ERROR_PAGEURL

Neden: pageurl parametresi eksik veya boş. Bu parametre, belirteç tabanlı CAPTCHA'lar (reCAPTCHA, Cloudflare Turnstile, GeeTest vb.) için gereklidir.

Düzeltme: Protokol de dahil olmak üzere CAPTCHA'nın yüklendiği sayfanın tam URL'sini ekleyin:

{
  "pageurl": ""
}

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

ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY

Neden: googlekey (sitekey) parametresi boş, hatalı biçimlendirilmiş veya eksik.

Düzeltme:

  1. Site anahtarını hedef sayfanın data-sitekey özelliğinden veya reCAPTCHA bağlantı URL'si k parametresinden yeniden çıkarın.
  2. Değerin boş veya kesik olmadığından emin olun.
{
  "googlekey": ""
}

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

ERROR_BAD_TOKEN_OR_PAGEURL

Neden: googlekey (sitekey) ve pageurl kombinasyonu geçersiz. Site anahtarı verilen sayfa URL'si için kayıtlı değil.

Genel nedenler:

  • reCAPTCHA widget'ı farklı bir alt alan adındaki bir iframe'in içine yüklenir. iframe URL'si yerine üst sayfa URL'sini kullanıyorsunuz.
  • Site anahtarı farklı bir sayfaya veya alana aittir.
  • Site anahtarı /staging geliştirme ortamından çıkarıldı.

Düzeltme:

  1. reCAPTCHA bir iframe içindeyse, iframe'in src URL'sini pageurl olarak kullanın.
  2. Canlı üretim sayfasından site anahtarını doğrulayın.
  3. reCAPTCHA bağlantı URL'sini manuel olarak yükleyerek her iki değeri de test edin: https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Neden: Yüklenen resim izin verilen maksimum boyutu aşıyor.

Düzeltme: Göndermeden önce resmi sıkıştırın veya yeniden boyutlandırın. Fotoğraflar için JPEG, ekran görüntüleri için PNG kullanın.

ERROR_ZERO_CAPTCHA_FILESIZE

Neden: Resim dosyası çok küçük (100 bayttan az), bu da yüklemenin boş veya bozuk olduğunu gösteriyor.

Düzeltme: Boş bir dosya veya bozuk base64 dizesi değil, gerçek görüntü verilerini gönderdiğinizi doğrulayın.

ERROR_WRONG_FILE_EXTENSION

Neden: Yüklenen dosyanın desteklenmeyen bir uzantısı var. Desteklenen: jpg, jpeg, png, gif.

Düzeltme: Yüklemeden önce görseli desteklenen bir formata dönüştürün.

ERROR_IMAGE_TYPE_NOT_SUPPORTED

Neden: Sunucu, dosya içeriğinden görüntü türünü belirleyemiyor.

Düzeltme: Standart bir formata (PNG veya JPEG) dönüştürün ve dosyanın bozuk olmadığından emin olun.

ERROR_UPLOAD

Neden: Sunucu, yüklenen dosyayı veya base64 yükünü okuyamadı.

Düzeltme:

  1. Dosya yüklemeleri için: çok parçalı form veri kodlamanızı doğrulayın.
  2. Base64 için: Base64 dizisinin eksiksiz olduğunu ve doğru şekilde kodlandığını doğrulayın.
  3. Dosya bozulmasını dışlamak için iyi olduğu bilinen bir görüntüyle test edin.

ERROR_BAD_PROXY

Neden: Sağladığınız proxy'ye ulaşılamıyor veya sistem tarafından hatalı olarak işaretlendi.

Düzeltme:

  1. Proxy'yi bağımsız olarak test edin; hedef siteye bağlanabilir mi?
  2. Farklı bir proxy deneyin.
  3. Formatı doğrulayın: IP kimlik doğrulamalı proxy'ler için login:password@IP:PORT veya IP:PORT.

Hesabınızda proxy kullanımı etkinleştirilmelidir. Bunu yapmadıysanız CaptchaAI desteğine başvurun.

ERROR_BAD_PARAMETERS

Neden: Gerekli parametreler eksik veya yanlış veri türlerine sahip.

Düzeltme: Çözmekte olduğunuz CAPTCHA türüne ilişkin API belgelerini kontrol edin ve gerekli tüm parametrelerin mevcut olduğunu doğrulayın:

CAPTCHA Türü Gerekli Parametreler
reCAPTCHA v2/v3 key, method=userrecaptcha, googlekey, pageurl
Cloudflare Turnstile key, method=turnstile, sitekey, pageurl
Cloudflare doğrulama akışı key, method=cloudflare_challenge, pageurl, proxy, proxytype
GeeTest v3 key, method=geetest, gt, challenge, pageurl
BLS key, method=bls, body, textinstructions
Normal/image key, method=post, file veya body

IP_BANNED

Neden: Tekrarlanan başarısız kimlik doğrulama denemelerinden sonra IP'niz geçici olarak yasaklandı.

Düzeltme: Yaklaşık 5 dakika bekleyin, ardından doğru kimlik bilgileriyle yeniden deneyin. Yanlış API anahtarlarıyla istek göndermeye devam etmeyin.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

Neden: Geçici bir sunucu tarafı hatası oluştu.

Düzeltme: 10 saniye bekleyip yeniden deneyin. Tekrarlanan hatalar için üstel gerilemeyi kullanın:

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

Yoklama hataları (res.php)

Bu hatalar, gönderilen bir görevin durumunu kontrol ettiğinizde ortaya çıkar.

CAPCHA_NOT_READY

Bu bir hata değildir. Çözümün hâlâ devam ettiği anlamına gelir.

Eylem: 5 saniye bekleyip tekrar anket yapın.

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

Zamanlama kılavuzu: | CAPTCHA Türü | Sonrasında ilk anket | Anket aralığı | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 saniye | 5 saniye | | Cloudflare Turnstile | 15 saniye | 5 saniye | | Cloudflare doğrulama akışı | 20 saniye | 5 saniye | | GeeTest v3 | 15 saniye | 5 saniye | | Normal/image CAPTCHA | 5 saniye | 5 saniye |

ERROR_CAPTCHA_UNSOLVABLE

Neden: CaptchaAI, birden fazla denemeden sonra CAPTCHA'yı çözemedi.

Genel nedenler:

  1. CAPTCHA türü desteklenmiyor veya parametreler yanlış.
  2. Sorgulama bozuk veya süresi dolmuş.
  3. Proxy tabanlı çözümler için: proxy çok yavaş veya ulaşılamıyor.
  4. Site CAPTCHA uygulamasını değiştirdi.

Düzeltme:

  1. Parametrelerinizin (sitekey, pageurl, method) doğru olduğunu doğrulayın.
  2. Yeni bir istekle yeniden gönderin.
  3. Proxy kullanıyorsanız farklı bir tane deneyin.
  4. Hata devam ederse site değişmiş olabilir; site anahtarını ve sayfa URL'sini yeniden çıkarın.

Aynı görev kimliğini yeniden denemeyin. Yeni parametrelerle yeni bir görev gönderin.

ERROR_WRONG_ID_FORMAT

Neden: Captcha kimliği yalnızca sayısal olmalıdır.

Düzeltme: in.php tarafından döndürülen kimliğin aynısını gönderdiğinizi doğrulayın (yalnızca rakamlar, fazladan karakter yok).

ERROR_WRONG_CAPTCHA_ID

Neden: Görev kimliği mevcut değil veya süresi dolmuş.

Düzeltme:

  1. Gönderiminizin getirdiği kimlikle oylama yaptığınızı doğrulayın.
  2. Görev kimliklerinin geçerliliği uzun süreler sonunda sona erebilir; görev çok eskiyse yeniden gönderin.

ERROR_EMPTY_ACTION

Neden: Yoklama isteğinizde action parametresi eksik veya boş.

Düzeltme: res.php isteğinize action=get ekleyin:

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

ERROR_PROXY_CONNECTION_FAILED

Neden: Çözümleyici, proxy'niz aracılığıyla hedef siteye bağlanamadı.

Düzeltme:

  1. Proxy geçici olarak kapalı olabilir; farklı bir tane deneyin.
  2. Hedef site proxy IP'sini engelliyor olabilir.
  3. Proxy'nin gerçekten hedef siteye ulaşabildiğini doğrulayın.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

Bunlar aynı zamanda res.php'de de görünebilir; yukarıdaki gönderme hatalarıyla aynı neden ve düzeltme.

Hata işleme şablonu

Güçlü hata işleme için bu modeli herhangi bir dilde kopyalayın:

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

SSS

CAPCHA_NOT_READY bir hata mı?

Hayır. Bu, çözümün hâlâ devam ettiği anlamına geliyor. 5 saniye bekleyin ve tekrar anket yapın. Bu her CAPTCHA türü için normaldir.

ERROR_CAPTCHA_UNSOLVABLE aldığımda ne yapmalıyım?

Yeni parametrelerle yeni bir görev gönderin. Aynı görev kimliğini yeniden denemeyin. Hata tekrar tekrar meydana geliyorsa site anahtarınızın ve sayfa url'nizin doğru olduğunu ve CAPTCHA türünün desteklendiğini doğrulayın.

Bir hatanın yeniden denenebilir olup olmadığını nasıl anlarım?

Parametre/format hataları (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, vb.) yeniden denenemez; önce isteği düzeltin. Sunucu hataları (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) üstel geri çekilmeyle yeniden denenebilir. ERROR_ZERO_BALANCE, iş parçacıklarının serbest kalması beklendikten sonra yeniden denenebilir.

Cloudflare doğrulama akışı için neden ERROR_BAD_PROXY alıyorum?

Cloudflare doğrulama akışı çalışan bir proxy gerektirir. Proxy'nin hedef siteye ulaşabilmesi gerekir. Bağımsız olarak test edin ve başarısız olursa farklı bir proxy deneyin. Ayrıca CaptchaAI hesabınızda proxy kullanımının etkinleştirildiğinden emin olun.

API anahtarımı nerede bulabilirim?

Giriş yapcaptchaai.comve gitcaptchaai.com/api.php. 32 karakterli API anahtarınız kontrol panelinde görüntülenir.

İlgili kılavuzlar

Bu makale için yorumlar devre dışı bırakılmıştır.