CaptchaAI Hata Kodları: Tam Referans ve Düzeltmeler

CaptchaAI API'sinden bir hata kodu döndüğünde asıl soru tek: isteği mi düzeltmeniz gerekiyor, birkaç saniye sonra yeniden mi denemelisiniz, yoksa çözüm hâlâ sürdüğü için beklemeniz mi yeterli? Bu üç davranıştan hangisinin geçerli olduğunu bilmek, kodun tam adını ezberlemekten çok daha işinize yarar. Aşağıdaki referans, CaptchaAI'nin döndürebileceği tüm hata kodlarını uç noktaya göre gruplayarak her birinin nedenini ve somut düzeltmesini verir.

Hatalar iki uç noktada ortaya çıkar:

• in.php — bir CAPTCHA görevi gönderdiğiniz uç nokta (hatalar gönderim anında oluşur)
• res.php — sonucu sorguladığınız uç nokta (hatalar sonuç alınırken oluşur)

İsteğinize json=1 eklerseniz hatalar JSON olarak döner:

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

json=1 olmadan aynı hata düz metin olarak geri gelir: ERROR_CODE_HERE

Hızlı triyaj: üç temel kural

Tam referansa geçmeden önce, vakaların yaklaşık %90'ını çözen üç kural şunlar:

Pratikte bu üç satır, gündelik bir işin çoğu hatasını doğru tarafa yönlendirir: ya isteği düzeltirsiniz, ya beklersiniz, ya da kontrollü aralıklarla yeniden denersiniz.

Gönderim hataları (in.php)

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

Kimlik doğrulama ve hesap hataları

Bu kodlar isteğinizin kimlik doğrulamasını veya hesabınızın thread durumunu ilgilendirir.

ERROR_WRONG_USER_KEY

Neden: key parametresi yanlış formatta. CaptchaAI API anahtarları 32 karakter uzunluğundadır.

Düzeltme:

1. Anahtarınızın tam olarak 32 karakter olduğundan emin olun.
2. Baş veya sondaki fazladan boşluk ya da satır sonu olmadığını kontrol edin.
3. Anahtarı doğrudan captchaai.com/api.php üzerinden kopyalayın.

Yanlış (sonunda boşluk var):

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

Doğru:

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

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

Düzeltme:

1. captchaai.com adresine giriş yapın ve anahtarı panelinizden kopyalayın.
2. Doğru hesabın anahtarını kullandığınızdan emin olun.
3. Hesabı yeni oluşturduysanız anahtarın etkinleşmesi için birkaç dakika bekleyin.

ERROR_ZERO_BALANCE

Neden: Hesabınızda görevi kabul edecek boş thread yok.

Düzeltme:

1. Çalışan görevlerin bitmesini bekleyin (thread'ler serbest kalır).
2. Daha fazla eş zamanlı thread için planınızı yükseltin — örneğin BASIC ($15/ay, 5 thread) planından STANDARD ($30/ay, 15 thread) planına.
3. Hesap bakiyenizi captchaai.com/api.php üzerinden kontrol edin.

Bu her zaman "bakiye bitti" hatası değildir. Aynı zamanda tüm thread'lerinizin şu an meşgul olduğu anlamına da gelebilir. Diyelim ki İstanbul'da bir müşteri için gece çalışan bir QA kazıma işi yürütüyorsunuz ve planınız tek thread'lik: bir görev işlenirken gönderdiğiniz yeni istekler, ilk görev tamamlanana kadar bu hatayı döndürür. Böyle bir işte darboğaz bakiye değil, eş zamanlı thread sayısıdır.

IP_BANNED

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

Düzeltme: Yaklaşık 5 dakika bekleyin, ardından doğru kimlik bilgileriyle yeniden deneyin. Yanlış API anahtarıyla istek göndermeyi sürdürmeyin.

Parametre ve sitekey hataları

Bu kodlar gönderdiğiniz parametrelerin biçimini veya sitekey ile pageurl eşleşmesini işaret eder.

ERROR_PAGEURL

Neden: pageurl parametresi eksik ya da boş. Bu parametre token tabanlı CAPTCHA'lar (reCAPTCHA, Cloudflare Turnstile, GeeTest vb.) için zorunludur.

Düzeltme: CAPTCHA'nın yüklendiği sayfanın protokol dahil 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ş ya da eksik.

Düzeltme:

1. Sitekey'i hedef sayfanın data-sitekey özniteliğinden veya reCAPTCHA anchor URL'sindeki k parametresinden yeniden çıkarın.
2. Değerin boş veya kesik olmadığını doğrulayın.

{
  "googlekey": ""
}

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

ERROR_BAD_TOKEN_OR_PAGEURL

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

Sık görülen nedenler:

• reCAPTCHA widget'ı farklı bir alt alan adındaki bir iframe içinde yükleniyor ve siz iframe URL'si yerine üst sayfanın URL'sini kullanıyorsunuz.
• Sitekey başka bir sayfaya veya alan adına ait.
• Sitekey bir staging/geliştirme ortamından çıkarılmış.

Düzeltme:

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

ERROR_BAD_PARAMETERS

Neden: Zorunlu parametreler eksik ya da yanlış veri tipinde.

Düzeltme: Çözdüğünüz CAPTCHA türüne ait API belgelerini kontrol edin ve gerekli tüm parametrelerin bulunduğunu doğrulayın:

Görsel yükleme hataları

Bu kodlar yalnızca görsel/OCR CAPTCHA gönderirken, yüklediğiniz dosyayla ilgili olarak çıkar.

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Neden: Yüklenen görsel izin verilen maksimum boyutu aşıyor.

Düzeltme: Göndermeden önce görseli 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: Görsel dosyası çok küçük (100 bayttan az); bu, yüklemenin boş veya bozuk olduğunu gösterir.

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

ERROR_WRONG_FILE_EXTENSION

Neden: Yüklenen dosyanın uzantısı desteklenmiyor. Desteklenenler: 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ı (multipart) form veri kodlamanızı doğrulayın.
2. Base64 için: dizenin eksiksiz ve doğru kodlanmış olduğunu doğrulayın.
3. Dosya bozulmasını elemek için sağlam olduğunu bildiğiniz bir görselle test edin.

Proxy ve sunucu hataları

Bu kodlar isteğin CaptchaAI'ye ulaşmasını engelleyen proxy veya geçici sunucu sorunlarını gösterir.

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ğlanabiliyor mu?
2. Farklı bir proxy deneyin.
3. Formatı doğrulayın: IP kimlik doğrulamalı proxy'ler için login:password@IP:PORT ya da IP:PORT.

Hesabınızda proxy kullanımının etkin olması gerekir. Bunu yapmadıysanız CaptchaAI desteğine başvurun.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

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

Düzeltme: 10 saniye bekleyip yeniden deneyin. Tekrarlayan hatalar için üstel geri çekilme (exponential backoff) uygulayı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

Sorgulama hataları (res.php)

Bu hatalar, gönderdiğiniz bir görevin durumunu sorguladığınızda ortaya çıkar.

Durum ve bekleme kodları

Bu yanıt bir hata değildir; çözümün hangi aşamada olduğunu söyler.

CAPCHA_NOT_READY

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

Eylem: 5 saniye bekleyip yeniden sorgulayın.

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

Sorgulama zamanlaması:

Görev ve parametre hataları

Bu kodlar sorguladığınız görevin kimliğiyle veya gönderdiğiniz parametrelerle ilgilidir.

ERROR_CAPTCHA_UNSOLVABLE

Neden: CaptchaAI, birden fazla denemenin ardından CAPTCHA'yı çözemedi.

Sık görülen nedenler:

1. CAPTCHA türü desteklenmiyor ya da parametreler yanlış.
2. Sorgu (challenge) bozuk veya süresi dolmuş.
3. Proxy tabanlı çözümlerde: proxy çok yavaş ya da ulaşılamıyor.
4. Site, CAPTCHA uygulamasını değiştirmiş.

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 sürüyorsa site değişmiş olabilir; sitekey'i ve pageurl'i 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 rakam, fazladan karakter yok).

ERROR_WRONG_CAPTCHA_ID

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

Düzeltme:

1. Gönderiminizin döndürdüğü kimlikle sorguladığınızı doğrulayın.
2. Görev kimlikleri uzun süre sonunda geçerliliğini yitirebilir; görev çok eskiyse yeniden gönderin.

ERROR_EMPTY_ACTION

Neden: Sorgulama isteğinizde action parametresi eksik ya da boş.

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

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

Bağlantı ve kimlik hataları

Bu kodlar sorgulama sırasında proxy bağlantısını veya API anahtarınızı ilgilendirir.

ERROR_PROXY_CONNECTION_FAILED

Neden: Çözümleyici, proxy'niz üzerinden 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 hedef siteye gerçekten ulaşabildiğini doğrulayın.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

Bu kodlar res.php'de de görünebilir; nedenleri ve düzeltmeleri yukarıdaki gönderim hatalarıyla aynıdır.

Sağlam hata işleme şablonu

Sağlam hata işleme için bu deseni herhangi bir dilde kopyalayabilirsiniz:

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

Sık sorulan sorular

ERROR_WRONG_USER_KEY ile ERROR_KEY_DOES_NOT_EXIST arasındaki fark nedir?

ERROR_WRONG_USER_KEY biçimsel bir sorundur: anahtar 32 karakter değildir ya da içinde fazladan boşluk/satır sonu vardır. ERROR_KEY_DOES_NOT_EXIST ise biçim doğru olsa bile anahtarın sistemdeki hiçbir hesaba karşılık gelmediği anlamına gelir. İlkinde anahtarın uzunluğunu, ikincisinde doğru hesabın anahtarını kullanıp kullanmadığınızı kontrol edin.

Bakiyem doluyken neden ERROR_ZERO_BALANCE alıyorum?

Bu hata her zaman parayla ilgili değildir. Çoğu zaman tüm thread'lerinizin o an dolu olduğunu gösterir. Tek thread'lik bir planınız varsa ve bir görev işleniyorsa, o görev bitene kadar yeni gönderimler bu hatayı döndürür. Çözüm ya çalışan görevlerin bitmesini beklemek ya da daha fazla eş zamanlı thread için planı yükseltmektir.

IP_BANNED aldıktan sonra ne kadar beklemeliyim?

Yaklaşık 5 dakika yeterlidir. Bu yasak, arka arkaya başarısız kimlik doğrulama denemelerinden sonra gelir; genellikle yanlış API anahtarıyla ısrarla istek göndermenin sonucudur. Beklerken önce anahtarınızı düzeltin, sonra doğru kimlik bilgileriyle yeniden başlayın — aksi hâlde süre yeniden uzar.

Hata kodları neden bazen JSON yerine düz metin dönüyor?

Yanıtın biçimini json=1 parametresi belirler. İsteğinize eklerseniz hatalar {"status": 0, "request": "..."} biçiminde JSON olarak döner; eklemezseniz aynı kod düz metin olarak (ERROR_CODE_HERE) gelir. Kodunuzda yanıtı ayrıştırmadan önce hangi biçimi beklediğinizi sabitleyin.

API anahtarımı nerede bulurum?

captchaai.com adresine giriş yapın ve captchaai.com/api.php sayfasına gidin. 32 karakterlik API anahtarınız panelde görüntülenir.

İlgili kılavuzlar

• CaptchaAI hızlı başlangıç rehberi — ilk çözümünüzü çalışır hâle getirin
• API ile reCAPTCHA v2 nasıl çözülür? — uçtan uca reCAPTCHA v2 eğitimi
• Cloudflare doğrulama akışı API ile nasıl çözülür? — proxy gerektiren Cloudflare çözümü
• Yaygın reCAPTCHA v2 çözüm hataları — reCAPTCHA'ya özgü sorun giderme