reCAPTCHA v2 Çözme Hataları ve Düzeltmeleri

reCAPTCHA v2 çözümü başarısız olduğunda sorun neredeyse her zaman dört yerden birindedir: yanlış googlekey, hatalı pageurl, çağrılmayan bir callback ya da süresi dolmuş bir token. API'den net bir hata kodu aldıysanız düzeltme çoğu zaman tek satırlıktır; asıl zor kısım, API geçerli bir token döndürdüğü hâlde hedef sayfanın onu sessizce reddettiği durumlardır.

reCAPTCHA v2 çözümüne yeni başladıysanız önce reCAPTCHA v2'yi API ile çözme rehberini okuyun. Bu yazı ise her hatayı istek (in.php), sonuç (res.php) ve token enjeksiyonu aşamalarına göre ele alır; başarısızlıkların büyük çoğunluğu şu dört kaynaktan çıkar:

• Yanlış veya eksik googlekey
• Hatalı pageurl
• Çağrılmayan callback
• Süresi dolmuş veya yeniden kullanılmış token

Belirtiye göre hızlı yönlendirme

Elinizde bir hata kodu ya da bir belirti varsa, önce aşağıdaki tabloya bakıp doğru bölüme atlayın.

reCAPTCHA v2 hatalarının dört ana kaynağı

Tek tek hata kodlarına inmeden önce şu dört kaynağı kontrol edin; başarısızlıkların yaklaşık %80'i buradan çıkar. Doğru sitekey'i sayfadan nasıl çıkaracağınızı tablonun hemen altındaki kod parçasında bulabilirsiniz.

# Look for data-sitekey in the page HTML
# <div class="g-recaptcha" data-sitekey="6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-"></div>

# Or find it in the anchor URL
# https://www.google.com/recaptcha/api2/anchor?k=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-

İstek aşaması hataları (in.php)

Bu hatalar, CAPTCHA görevini https://ocr.captchaai.com/in.php adresine gönderdiğinizde ortaya çıkar.

Örnek: hata yönetimli doğru istek

import requests

def submit_recaptcha_v2(api_key, sitekey, page_url):
    response = requests.get("https://ocr.captchaai.com/in.php", params={
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "json": 1
    })

    data = response.json()

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

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

    if error == "ERROR_WRONG_USER_KEY":
        raise ValueError("API key format is invalid. Must be 32 characters.")
    elif error == "ERROR_ZERO_BALANCE":
        raise RuntimeError("Account balance is zero. Top up at captchaai.com")
    elif error == "ERROR_PAGEURL":
        raise ValueError("pageurl parameter is missing from request")
    elif error in ("ERROR_GOOGLEKEY", "ERROR_WRONG_GOOGLEKEY"):
        raise ValueError(f"Invalid sitekey. Verify the data-sitekey value on the page.")
    elif error == "ERROR_BAD_TOKEN_OR_PAGEURL":
        raise ValueError("Sitekey/pageurl mismatch. Check if widget is in an iframe.")
    else:
        raise RuntimeError(f"API error: {error}")

# Usage
task_id = submit_recaptcha_v2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://staging.example.com/qa-login")
print(f"Task submitted: {task_id}")

Aynı isteğin Node.js karşılığı da hataları tek tek ayırt eder:

async function submitRecaptchaV2(apiKey, sitekey, pageUrl) {
  const params = new URLSearchParams({
    key: apiKey,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageUrl,
    json: 1,
  });

  const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const data = await res.json();

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

  const error = data.request || "UNKNOWN_ERROR";
  const fixes = {
    ERROR_WRONG_USER_KEY: "API key format is invalid. Must be 32 characters.",
    ERROR_ZERO_BALANCE: "Account balance is zero. Top up at captchaai.com",
    ERROR_PAGEURL: "pageurl parameter is missing from request",
    ERROR_GOOGLEKEY: "Invalid sitekey. Check the data-sitekey attribute.",
    ERROR_BAD_TOKEN_OR_PAGEURL: "Sitekey/pageurl mismatch. Check iframe context.",
  };

  throw new Error(fixes[error] || `API error: ${error}`);
}

// Usage
const taskId = await submitRecaptchaV2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://staging.example.com/qa-login");
console.log(`Task submitted: ${taskId}`);

Sonuç aşaması hataları (res.php)

Bu hatalar, sonucu almak için https://ocr.captchaai.com/res.php adresini sorguladığınızda ortaya çıkar.

Örnek: doğru sorgulama döngüsü

import time
import requests

def poll_result(api_key, task_id, timeout=120):
    start = time.time()

    while time.time() - start < timeout:
        time.sleep(5)

        response = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1
        })

        data = response.json()

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

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

        if error == "CAPCHA_NOT_READY":
            continue  # normal — keep waiting
        elif error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable. Submit a new task with fresh params.")
        elif error in ("ERROR_WRONG_ID_FORMAT", "ERROR_WRONG_CAPTCHA_ID"):
            raise ValueError(f"Invalid task ID: {task_id}")
        else:
            raise RuntimeError(f"Polling error: {error}")

    raise TimeoutError(f"Solve timed out after {timeout}s")

# Usage
token = poll_result("YOUR_API_KEY", task_id)
print(f"Token: {token[:50]}...")

Node.js karşılığı aynı sorgulama aralığını ve zaman aşımını korur:

async function pollResult(apiKey, taskId, timeout = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    await new Promise((r) => setTimeout(r, 5000));

    const params = new URLSearchParams({
      key: apiKey,
      action: "get",
      id: taskId,
      json: 1,
    });

    const res = await fetch(`https://ocr.captchaai.com/res.php?${params}`);
    const data = await res.json();

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

    if (data.request === "CAPCHA_NOT_READY") continue;
    if (data.request === "ERROR_CAPTCHA_UNSOLVABLE")
      throw new Error("Unsolvable. Submit a new task.");
    throw new Error(`Polling error: ${data.request}`);
  }

  throw new Error(`Solve timed out after ${timeout / 1000}s`);
}

Token geçerli ama sayfa reddediyor

API geçerli bir token döndürdü ama hedef site onu yine de reddediyor. Bunlar en zor teşhis edilen hatalardır çünkü API tarafında her şey yolunda görünür. Bir token'ın geçerli olup da neden reddedildiğini anlamak için şu üç noktayı sırayla kontrol edin:

• Sayfa gizli alan mı, callback mi, yoksa ikisini birden mi bekliyor?
• pageurl gerçek widget bağlamıyla — özellikle iframe'lerle — eşleşiyor mu?
• Token'ı almakla göndermek arasında 2 dakikadan fazla süre geçti mi?

Token yanlış alana enjekte edildi

Bazı sayfalar token'ı g-recaptcha-response textarea'sında arar. Bazıları grecaptcha.getResponse() kullanır. Bazıları ise bir callback bekler. Yanlış enjeksiyon yöntemini seçerseniz form gönderimi sessizce başarısız olur. Beklenen yolu belirlemek için sayfayı inceleyin ve uygun yöntemi uygulayın:

# Method 1: Hidden field injection
driver.execute_script(
    'document.getElementById("g-recaptcha-response").innerHTML = arguments[0];',
    token
)

# Method 2: Callback execution (check data-callback attribute)
driver.execute_script(f'onCaptchaSuccess("{token}");')

# Method 3: Direct form field + submit
driver.execute_script(
    'document.querySelector("[name=g-recaptcha-response]").value = arguments[0];',
    token
)
driver.find_element("css selector", "form").submit()

Callback tetiklenmedi

Widget'ta data-callback="onSuccess" varsa ya da grecaptcha.render() bir callback özelliğiyle kullanılıyorsa, yalnızca gizli alanı doldurmak hiçbir işe yaramaz. Callback fonksiyonunu bulup doğrudan çağırmanız gerekir:

// In browser console or Puppeteer/Playwright
// Check for data-callback
const widget = document.querySelector('.g-recaptcha');
const callbackName = widget?.getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

Geriye kalan iki neden zamanlama ve iframe bağlamıyla ilgilidir; ikisi de API tarafında görünmez:

Yerel bir örnek: İstanbul merkezli bir ekipte e-ticaret ödeme akışını QA eden bir otomasyon geliştiricisi düşünün. staging.example.com/qa-login sayfasındaki reCAPTCHA aslında ayrı bir alt alanda barındırılan bir iframe içinde yükleniyor. pageurl olarak üst sayfa gönderildiği için her istek ERROR_BAD_TOKEN_OR_PAGEURL dönüyordu; pageurl iframe'in src adresiyle değiştirildiğinde akış ilk denemede geçti.

Sık sorulan sorular

reCAPTCHA v2 çözümü ne kadar sürer?

Tipik reCAPTCHA v2 çözüm süresi 15–60 saniyedir; zorlu görsel görevlerde biraz daha uzayabilir. res.php'yi 5 saniyede bir sorgulayın ve zaman aşımını en az 120 saniye tutun. Bekleme sırasında dönen CAPCHA_NOT_READY yanıtı normaldir, hata değildir.

googlekey ile sitekey aynı şey mi?

Evet, ikisi aynı değerdir. İstekteki alanın adı googlekey, sayfadaki niteliğin adı ise data-sitekey'dir; dokümantasyon çoğu zaman ona sitekey der. Görevi gönderirken sayfadaki data-sitekey değerinin aynısını googlekey olarak geçirdiğinizden emin olun.

reCAPTCHA v2 için yazdığım kod reCAPTCHA Enterprise'da neden çalışmıyor?

reCAPTCHA Enterprise, standart reCAPTCHA v2'den farklı parametreler bekler ve aynı akışla birebir çözülmez. ERROR_CAPTCHA_UNSOLVABLE sürekli tekrar ediyorsa, hedefin gerçekten standart reCAPTCHA v2 mı yoksa Enterprise mı olduğunu doğrulayıp isteğinizi buna göre yapılandırın.

CaptchaAI hCaptcha veya FunCaptcha hatalarında da yardımcı olur mu?

Hayır. CaptchaAI reCAPTCHA v2 / v3, reCAPTCHA Enterprise ve Cloudflare Turnstile gibi türleri destekler; hCaptcha ve FunCaptcha (Arkose Labs) desteklenmez. Bu türlerde bir hata alıyorsanız sorun yapılandırmanızda değil, CAPTCHA türünün kapsam dışı olmasındadır.

reCAPTCHA v2 iş akışınızı sağlamlaştırın

1. Girdilerinizi doğrulayın — googlekey'i data-sitekey'den çıkarın ve tam sayfa URL'sini kullanın (iframe'leri kontrol edin).
2. Enjeksiyon yöntemini belirleyin — sayfa gizli alan mı, callback mi yoksa ikisini birden mi bekliyor?
3. Hemen gönderin — token'ı aldıktan sonraki 2 dakika içinde kullanın.
4. Hata yönetimi ekleyin — her hata türünü yakalayıp işlemek için yukarıdaki kod örneklerini kullanın.

CaptchaAI thread tabanlı, aylık sabit USD fiyatlandırma kullanır — BASIC ($15/ay, 5 thread) ile başlayıp hacim arttıkça yükseltebilirsiniz. CaptchaAI çözücü ile reCAPTCHA v2 çözmeye başlayın; API anahtarınızı captchaai.com/api.php üzerinden alın.

İlgili kılavuzlar

• reCAPTCHA v2 callback sorununu çözme — callback'e özel rehber
• reCAPTCHA ızgara doğrulaması nasıl çalışır? — ızgara görevlerinin açıklaması
• CaptchaAI hata kodları referansı — tam hata kodu listesi