reCAPTCHA v2 Enterprise hataları ve çözümleri

reCAPTCHA v2 Enterprise token'ınız CaptchaAI API'den başarıyla dönüyor ama hedef site onu reddediyorsa, sorun neredeyse her zaman tek bir eksik parametrede düğümlenir: enterprise=1. Enterprise widget'ını standart v2 gibi çözerseniz üretilen token doğru biçimdedir, ama Enterprise arka ucunun doğrulamasından geçmez ve istek reddedilir. İstanbul merkezli bir e-ticaret ekibinin ödeme akışını KVKK uyumlu bir QA ortamında test eden bir otomasyon geliştiricisiyseniz, bu tek satırlık farkın tüm test gecenizi harcatabileceğini bilirsiniz.

Bu rehber, reCAPTCHA v2 Enterprise'ı CaptchaAI API ile çözerken karşılaştığınız hataları tek tek ele alır: yanlış parametre, eksik data-s, sitekey uyumsuzluğu ve süresi dolmuş token'lar. Standart v2 ile mi yoksa Enterprise ile mi uğraştığınızdan emin değilseniz, önce Enterprise uygulamasını nasıl tespit edeceğinize bakın.

Hızlı teşhis: belirtiden hataya

Zaman kaybetmeden doğru bölüme geçmek için önce belirtinizi eşleştirin:

• Token dönüyor ama site reddediyor → büyük olasılıkla enterprise=1 eksik.
• ERROR_BAD_PARAMETERS alıyorsunuz → sayfada data-s var ama isteğinize eklemediniz.
• Token bazen çalışıyor bazen reddediliyor → widget'ı yanlış türde (standart/Enterprise) tanımlamış olabilirsiniz.
• ERROR_WRONG_USER_KEY veya ERROR_ZERO_BALANCE → sürümden bağımsız, hesap/anahtar düzeyinde bir sorun.

Aşağıdaki bölümler her belirtiyi nedeni ve çalışan çözümüyle birlikte açıklar.

Enterprise'a özgü hatalar ve çözümleri

enterprise=1 bayrağını göndermemek

• Belirti: API bir token döndürüyor, ancak hedef site onu reddediyor.
• Neden: Görevi enterprise=1 olmadan gönderdiniz. CaptchaAI bunu standart v2 olarak çözdü; oysa arka uç, standart token'ları kabul etmeyen Enterprise API'sine göre doğrulama yapıyor.
• Çözüm: İsteğinize enterprise=1 ekleyin.

Standart v2 için çalışan kodunuz varsa, değişecek tek şey bu bayraktır:

import requests

response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
    "pageurl": "https://staging.example.com/qa-login",
    "enterprise": 1,
    "json": 1
})

data = response.json()
task_id = data["request"]

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  method: "userrecaptcha",
  googlekey: "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
  pageurl: "https://staging.example.com/qa-login",
  enterprise: 1,
  json: 1,
});

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

data-s parametresini atlamak

• Belirti: ERROR_BAD_PARAMETERS alıyorsunuz ya da token site tarafından reddediliyor.
• Neden: Bazı Enterprise uygulamaları, reCAPTCHA div'inde bir data-s özniteliği taşır. Bu, çözüm için gereken ek bir oturum token'ıdır.
• Çözüm: Sayfada data-s varsa değerini isteğinize ekleyin.

Öznitelik mevcutsa, kodunuz şöyle görünmeli:

# Look for: <div class="g-recaptcha" data-sitekey="..." data-s="..."></div>
response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": sitekey,
    "pageurl": page_url,
    "enterprise": 1,
    "data-s": data_s_value,  # Include if present on the page
    "json": 1
})

Widget'ı yanlış türde tanımlamak

• Belirti: Token tutarsız çalışıyor ya da her seferinde reddediliyor.
• Neden: Aslında Enterprise olan bir widget'ı standart olarak (veya tam tersi) tanımladınız.
• Çözüm: Sayfa HTML'sindeki script kaynağını ve JS nesnesini kontrol edin.

Aşağıdaki işaretler hangi sürümle çalıştığınızı kesinleştirir:

// Enterprise uses enterprise.js
// <script src="https://www.google.com/recaptcha/enterprise.js?render=SITEKEY"></script>

// Standard uses api.js
// <script src="https://www.google.com/recaptcha/api.js"></script>

// Also check the JS object:
// Enterprise: grecaptcha.enterprise.render(...)
// Standard: grecaptcha.render(...)

Referans: Enterprise ve standart v2 arasındaki farklar

Hatanın kökü çoğu zaman iki sürümü birbirine karıştırmaktır. Bir sonraki entegrasyonda hangi değerin nereye gittiğini görmek için bu tabloyu başucu referansı olarak kullanın.

İpucu: Sürümü hızlıca ayırt etmek için tarayıcı konsolunda grecaptcha.enterprise nesnesinin tanımlı olup olmadığına bakın; tanımlıysa sayfa Enterprise sürümünü kullanıyordur.

Standart v2 ile ortak hata kodları

Aşağıdaki kodlar Enterprise'a özgü değildir; her iki sürümde de görülür ve CaptchaAI yanıtının request alanında döner.

Hata yönetimiyle eksiksiz çözüm akışı

Aşağıdaki iki örnek görev gönderme, sonucu sorgulama ve hata durumlarını yönetmeyi tek fonksiyonda toplar. Fonksiyon üç işi birden üstlenir:

• Görevi enterprise=1 (ve varsa data-s) ile gönderir.
• Sonucu her 5 saniyede bir sorgular ve CAPCHA_NOT_READY durumunda beklemeye devam eder.
• Zaman aşımı, gönderim hatası ve çözüm hatasını ayrı ayrı ele alır.

import requests
import time

def solve_recaptcha_v2_enterprise(api_key, sitekey, page_url, data_s=None):
    params = {
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "enterprise": 1,
        "json": 1
    }
    if data_s:
        params["data-s"] = data_s

    response = requests.get("https://ocr.captchaai.com/in.php", params=params)
    data = response.json()

    if data.get("status") != 1:
        raise RuntimeError(f"Submit failed: {data.get('request')}")

    task_id = data["request"]

    for _ in range(40):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key, "action": "get", "id": task_id, "json": 1
        }).json()

        if result.get("status") == 1:
            return result["request"]
        if result.get("request") == "CAPCHA_NOT_READY":
            continue
        raise RuntimeError(f"Solve failed: {result.get('request')}")

    raise TimeoutError("Solve timed out after 200 seconds")

token = solve_recaptcha_v2_enterprise("YOUR_API_KEY", "SITEKEY", "https://staging.example.com/qa-login")

async function solveRecaptchaV2Enterprise(apiKey, sitekey, pageUrl, dataS) {
  const params = new URLSearchParams({
    key: apiKey, method: "userrecaptcha", googlekey: sitekey,
    pageurl: pageUrl, enterprise: 1, json: 1,
  });
  if (dataS) params.set("data-s", dataS);

  const submitRes = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const submitData = await submitRes.json();
  if (submitData.status !== 1) throw new Error(`Submit failed: ${submitData.request}`);

  const taskId = submitData.request;
  for (let i = 0; i < 40; i++) {
    await new Promise(r => setTimeout(r, 5000));
    const res = await fetch(`https://ocr.captchaai.com/res.php?${new URLSearchParams({
      key: apiKey, action: "get", id: taskId, json: 1,
    })}`);
    const data = await res.json();
    if (data.status === 1) return data.request;
    if (data.request === "CAPCHA_NOT_READY") continue;
    throw new Error(`Solve failed: ${data.request}`);
  }
  throw new Error("Timed out after 200s");
}

Not: Enterprise token'ları da yaklaşık 2 dakika sonra geçerliliğini yitirir. Sorgulama tamamlandığı anda token'ı beklemeden hedef forma gönderin; aksi halde geçerli bir token bile "reddedildi" gibi görünür.

Sık sorulan sorular

Enterprise entegrasyonlarında en çok tekrarlanan sorular ve kısa yanıtları aşağıda.

Enterprise token'ı ne kadar sürede geçerliliğini yitirir?

Yaklaşık 2 dakika. Standart v2 gibi Enterprise token'ları da kısa ömürlüdür; token'ı aldıktan sonra formu hemen gönderin. Sorgulama döngünüz ile form gönderimi arasında uzun bir bekleme varsa, token siz kullanmadan süresini doldurmuş olabilir.

CaptchaAI reCAPTCHA v3 Enterprise'ı da destekliyor mu?

Evet. reCAPTCHA v3 Enterprise da desteklenen türler arasında ve v2 gibi userrecaptcha yöntemini kullanır. Fark, v3'ün ek olarak action ve puan (score) beklentisiyle çalışmasıdır; bu parametreleri sayfanın v3 yapılandırmasına göre ayarlarsınız.

CaptchaAI hCaptcha veya FunCaptcha'yı çözer mi?

Hayır. CaptchaAI şu an hCaptcha ve FunCaptcha (Arkose Labs) türlerini çözmez. Karşılaştırma yaparken bu türler için dürüst bir "henüz desteklenmiyor" ifadesi kullanın; desteklenen türler reCAPTCHA ailesi, Cloudflare Turnstile ve Challenge, GeeTest v3, görüntü/OCR, grid ve BLS'tir.

enterprise=1 eklediğim halde token neden hâlâ reddediliyor?

Sırasıyla üç şeyi kontrol edin:

• sitekey doğru mu ve iframe'deki değerle birebir aynı mı?
• Sayfada data-s var mı, varsa isteğinize eklediniz mi?
• Token'ı formu göndermeden önce süresi dolmadan kullandınız mı?

data-s değerini sayfada nasıl bulurum?

Şu iki adımı izleyin:

• reCAPTCHA'yı barındıran <div class="g-recaptcha"> öğesini bulun ve data-s özniteliği olup olmadığına bakın.
• Öznitelik varsa değerini alıp API isteğinize data-s parametresi olarak ekleyin; yoksa uygulama bunu kullanmıyordur ve göndermenize gerek yoktur.

Enterprise iş akışınızı düzeltme adımları

Yeni bir Enterprise sitesine geçtiğinizde bu dört adımı kontrol listesi gibi işletin; çoğu "token reddedildi" vakası ilk iki adımda çözülür.

1. Uygulama türünü doğrulayın — script etiketinde enterprise.js olup olmadığını kontrol edin
2. İsteğinize enterprise=1 ekleyin
3. data-s'yi kontrol edin — sayfa bu özniteliğe sahipse değeri isteğinize ekleyin
4. Token'ı hemen gönderin — Enterprise token'ları da yaklaşık 2 dakika sonra geçerliliğini yitirir

API anahtarınızı şu adresten alın: captchaai.com/api.php.

İlgili kılavuzlar

• reCAPTCHA Enterprise uygulamasını nasıl tespit edersiniz
• API ile reCAPTCHA v2 nasıl çözülür
• Standart ve Enterprise reCAPTCHA v2 karşılaştırması
• CaptchaAI hata kodları başvurusu