Cloudflare Turnstile Hataları ve Sorun Giderme

Turnstile entegrasyonunuz bir token döndürüyor ama sayfa onu kabul etmiyorsa, sorun neredeyse her zaman üç yerden birindedir: gönderdiğiniz pageurl, yakaladığınız sitekey veya token'ı uyguladığınız yol. Turnstile hatalarını hızlı çözmenin anahtarı, hatanın hangi aşamada oluştuğunu ilk bakışta ayırt etmektir.

Her Turnstile hatası üç aşamadan birine düşer:

• İstek aşaması — göreviniz in.php uç noktasında reddedilir (parametre hatası).
• Sonuç aşaması — sorgulama başarısız olur veya zaman aşımına uğrar.
• Doğrulama aşaması — API geçerli bir token döndürür, ama hedef sayfa onu reddeder.

CaptchaAI'nin Turnstile çözücüsü bu doğrulamayı genellikle 10 saniyenin altında, yüksek bir başarı oranıyla çözer. Entegrasyonunuz başarısız olduğunda kusur çözümde değil, gönderdiğiniz parametrelerde ya da dönen token'ı uygulama şeklinizdedir. Aşağıda önce doğru ürünü ve doğru aşamayı belirliyor, sonra her hata kodunu gerçek bir düzeltmeye bağlıyoruz.

Önce hangi Cloudflare ürünüyle karşı karşıyasınız?

Sorun gidermeye başlamadan önce hangi Cloudflare doğrulamasıyla uğraştığınızı netleştirin. İkisi farklı API yöntemleri kullanır, farklı çıktılar döndürür ve yanlış olanı hedeflerseniz hata kodları da yanıltıcı olur.

Gömülü bir widget değil de tam sayfa bir Cloudflare doğrulama ekranıyla karşılaşıyorsanız, bunun yerine bir qa_session_cookie çerezi döndüren ve proxy gerektiren Cloudflare doğrulama akışı çözücüsüne ihtiyacınız olur. Bu yazının geri kalanı gömülü Turnstile widget'ına odaklanır.

Turnstile'ı diğer CAPTCHA'lardan ayıran üç nokta

Hata kodlarını incelemeden önce, Turnstile'ı özel kılan ve sorunların çoğunu üreten üç davranışı bilin. Bu üç noktayı kavrarsanız gördüğünüz hataların çoğunu, tek tek kod arama gereği kalmadan doğru aşamaya oturtabilirsiniz.

• Tam sayfa URL'si burada daha kritiktir. Turnstile token'ları sayfa bağlamına sıkı sıkıya bağlıdır; özellikle tam sayfa Cloudflare doğrulama ekranlarında biraz farklı bir pageurl (örneğin eksik bir sorgu parametresi) bile token'ın reddedilmesine yol açar.
• Token'ı uygulamanın iki yolu vardır. Dönen token ya gizli bir form alanına yazılır ya da bir callback işleviyle iletilir; yanlış olanı seçmek sessizce başarısız olur.
• Her token yalnızca bir kez geçerlidir. Bir Turnstile token'ı yalnızca bir kez doğrulanabilir; otomasyonunuz onu iki kez gönderirse veya bir yarış durumu (race condition) oluşursa ikinci deneme başarısız olur.

Token'ı hangi yolla uygulayacağınız tamamen sayfanın tasarımına bağlıdır:

Hata-çözüm hızlı başvuru tablosu

Bir hata kodu gördüyseniz önce şu tabloda arayın: her kodu aşamasına ve tek satırlık düzeltmesine bağlar. Ayrıntılı açıklamaları ve kod örneklerini aşağıdaki bölümlerde bulacaksınız.

Kodunuz tabloda yoksa, hatayı şu üç soruyla doğru aşamaya oturtun:

1. Görev in.php uç noktasında mı reddedildi? → İstek aşaması (parametreleri kontrol edin).
2. res.php sorgusu mu başarısız oluyor veya boş dönüyor? → Sonuç aşaması (ID ve action alanına bakın).
3. API bir token verdi ama sayfa mı reddediyor? → Doğrulama aşaması (alan, callback ve pageurl).

İstek aşaması hataları: gönderim reddediliyor

Bunlar, görevi https://ocr.captchaai.com/in.php uç noktasına gönderirken ortaya çıkar. Çoğu tek satırda düzeltilir; aşağıdaki tablo dört yaygın kodu ve doğrudan düzeltmesini toplar.

Geri kalan iki istek hatası bir tablo satırına sığmaz, çünkü ek yapılandırma gerektirir.

ERROR_PAGEURL

Neden: pageurl parametresi eksik.

Düzeltme: Protokol, alan adı ve yolu içeren tam URL'yi ekleyin:

pageurl=https://staging.example.com/qa-login

ERROR_BAD_PARAMETERS

Neden: Zorunlu parametreler eksik veya hatalı biçimlendirilmiş. Turnstile için zorunlu parametreler şunlardır:

İsteğe bağlı ama işe yarar:

Düzeltme: Tüm zorunlu alanların mevcut ve doğru türde olduğunu doğrulayın.

Turnstile sitekey'ini nerede bulursunuz?

sitekey, en sık hatalı gönderilen parametredir. Onu şu üç yerde bulabilirsiniz.

Seçenek 1 — data-sitekey özelliği:

<div class="cf-turnstile" data-sitekey="0x4AAAAAAAB1example"></div>

Seçenek 2 — turnstile.render() çağrısı:

turnstile.render('#captcha-container', {
  sitekey: '0x4AAAAAAAB1example',
  callback: function(token) {
    document.getElementById('cf-turnstile-response').value = token;
  }
});

Seçenek 3 — render çağrısını yakalama (ileri seviye):

sitekey dinamik olarak yükleniyorsa, widget başlatılmadan önce turnstile.render'ı yeniden tanımlayarak parametreleri yakalayabilirsiniz:

// Inject this before the Turnstile script loads
const originalRender = window.turnstile.render;
window.turnstile.render = function(container, params) {
  console.log('Sitekey:', params.sitekey);
  console.log('Action:', params.action);
  return originalRender.call(this, container, params);
};

Sonuç aşaması hataları: sorgulama sırasında

Bunlar, https://ocr.captchaai.com/res.php uç noktasını sorgularken ortaya çıkar. Aşağıdaki tablo, sorgulama sırasında dönebilecek durumları özetler — ilki aslında bir hata değildir.

İpucu: ERROR_CAPTCHA_UNSOLVABLE birkaç istek boyunca sürüyorsa, çoğu zaman sorun çözümde değildir — sayfanın beklediğinden farklı bir widget örneğinin sitekey'ini gönderiyorsunuzdur. Sitekey'i yeniden çıkarın.

Yalnızca bir sonuç kodu tablo yerine kendi adımını gerektirir:

ERROR_EMPTY_ACTION

Neden: Sorgu isteğinizde action parametresi eksik.

Düzeltme: Her zaman action=get'i ekleyin:

https://ocr.captchaai.com/res.php?key=YOUR_KEY&action=get&id=CAPTCHA_ID&json=1

Not: Turnstile sonuçlarını sorgularken daima json=1 kullanın. JSON yanıtı, bazı Cloudflare korumalı sayfaların başarılı token doğrulaması için ihtiyaç duyduğu user_agent bilgisini de içerebilir.

Hedef sayfa token'ı reddediyor: doğrulama hataları

Bunların hata ayıklaması en zorudur, çünkü API başarıyla bir token döndürür ama hedef sayfa onu reddeder.

Yerel bir örnek: e-ticaret ödeme akışı QA'sı

Türkiye'de e-ticaret ve fintech entegrasyonları geliştiren ekiplerin çoğu, giriş ve ödeme (checkout) akışlarını staging.example.com gibi test ortamlarında otomatik olarak doğrular. Tipik sorun şudur: CaptchaAI geçerli bir token döndürür, ama staging giriş sayfası onu reddeder. Neden neredeyse her zaman aynıdır — tek sayfalı uygulamanın (SPA) görünen URL'si ile widget'ın gerçekten yüklendiği URL farklıdır, yani pageurl uyuşmaz.

Bu ekipler için pratik kural şudur: token reddediliyorsa pageurl olarak tarayıcının adres çubuğundaki URL'yi değil, widget'ı yükleyen isteğin URL'sini gönderin. Staging ortamlarında giriş ve ödeme sayfaları çoğu zaman farklı alt yollarda (/qa-login, /qa-checkout) çalışır; bu yolları koda sabitlemek yerine DevTools'tan doğrulayın. Böyle QA akışlarında yalnızca yetkilendirilmiş test verileriyle çalışın; kişisel veri işleniyorsa KVKK yükümlülüklerinizi göz ardı etmeyin.

Hata 1: Token yanlış alana yazıldı

Belirti: Form gönderiliyor ama sayfa doğrulama hatası veriyor ya da yeniliyor.

Turnstile sayfaları token'ı farklı alanlarda bekleyebilir:

• cf-turnstile-response — birincil Turnstile gizli girişi
• g-recaptcha-response — bazı sayfalar bunu yedek olarak kullanır

Düzeltme: Sayfanın formunu her iki alan için de kontrol edin. Tarayıcı otomasyonunda:

# Selenium — inject into both fields for safety
driver.execute_script("""
    var cfField = document.querySelector('[name="cf-turnstile-response"]');
    var gField = document.querySelector('[name="g-recaptcha-response"]');
    if (cfField) cfField.value = arguments[0];
    if (gField) gField.value = arguments[0];
""", token)

Hata 2: Callback tetiklenmedi

Belirti: Token alanda duruyor ama form gönderimi hâlâ engelliyor.

Neden: Sayfa, gizli alan yerine (ya da ona ek olarak) bir callback işlevi kullanıyor. Callback; gönder düğmesini etkinleştirmek veya bir AJAX isteği yollamak gibi ek mantığı yürütür.

Düzeltme: Callback'i bulun ve çağırın:

// Check data-callback attribute
const callbackName = document.querySelector('.cf-turnstile').getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

// Or if it was passed in turnstile.render()
// You may need to intercept the render call to capture it

Kalan iki doğrulama hatası kod gerektirmez; belirti ve düzeltmeleri tek tabloda toplanabilir:

Python ile tam Turnstile çözümü

import time
import requests

API_KEY = "YOUR_CAPTCHAAI_API_KEY"
SITEKEY = "0x4AAAAAAAB1example"
PAGE_URL = "https://staging.example.com/qa-login"

SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"


def solve_turnstile(api_key, sitekey, pageurl):
    """Submit a Turnstile challenge and return the solved token."""

    # Submit
    submit_resp = requests.post(
        SUBMIT_URL,
        data={
            "key": api_key,
            "method": "turnstile",
            "sitekey": sitekey,
            "pageurl": pageurl,
            "json": 1,
        },
        timeout=30,
    )
    submit_resp.raise_for_status()
    submit_data = submit_resp.json()

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

    captcha_id = submit_data["request"]
    print(f"Task created — captcha ID: {captcha_id}")

    # Wait before first poll (Turnstile is fast — 10 seconds is usually enough)
    time.sleep(10)

    # Poll for result
    for _ in range(60):
        result_resp = requests.get(
            RESULT_URL,
            params={
                "key": api_key,
                "action": "get",
                "id": captcha_id,
                "json": 1,
            },
            timeout=30,
        )
        result_resp.raise_for_status()
        result_data = result_resp.json()

        if result_data.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result_data.get("status") == 1:
            return result_data["request"]

        raise RuntimeError(f"Polling error: {result_data}")

    raise TimeoutError("Turnstile solve timed out")


# Usage
token = solve_turnstile(API_KEY, SITEKEY, PAGE_URL)
print(f"Solved token: {token[:80]}...")

# Inject into cf-turnstile-response and/or g-recaptcha-response
# Then submit the form

Node.js ile tam Turnstile çözümü

const API_KEY = "YOUR_CAPTCHAAI_API_KEY";
const SITEKEY = "0x4AAAAAAAB1example";
const PAGE_URL = "https://staging.example.com/qa-login";

const SUBMIT_URL = "https://ocr.captchaai.com/in.php";
const RESULT_URL = "https://ocr.captchaai.com/res.php";

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function solveTurnstile(apiKey, sitekey, pageurl) {
  // Submit
  const submitResp = await fetch(SUBMIT_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      key: apiKey,
      method: "turnstile",
      sitekey: sitekey,
      pageurl: pageurl,
      json: "1",
    }),
  });

  const submitData = await submitResp.json();
  if (submitData.status !== 1) {
    throw new Error(`Submit failed: ${JSON.stringify(submitData)}`);
  }

  const captchaId = submitData.request;
  console.log(`Task created — captcha ID: ${captchaId}`);

  // Turnstile is fast — wait 10 seconds before first poll
  await sleep(10_000);

  // Poll for result
  for (let i = 0; i < 60; i++) {
    const resultResp = await fetch(
      `${RESULT_URL}?${new URLSearchParams({
        key: apiKey,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );

    const resultData = await resultResp.json();

    if (resultData.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }

    if (resultData.status === 1) {
      return resultData.request;
    }

    throw new Error(`Polling error: ${JSON.stringify(resultData)}`);
  }

  throw new Error("Turnstile solve timed out");
}

// Usage
solveTurnstile(API_KEY, SITEKEY, PAGE_URL)
  .then((token) => {
    console.log(`Solved token: ${token.slice(0, 80)}...`);
    // Inject into cf-turnstile-response and/or g-recaptcha-response
  })
  .catch(console.error);

SSS

Turnstile token'ının geçerlilik süresi ne kadar?

Turnstile token'ları hem tek kullanımlık hem de kısa ömürlüdür. Çözümü aldıktan hemen sonra gönderin; bekletir veya önbelleğe alırsanız hedef sayfa büyük olasılıkla reddeder. Her form gönderimi için taze bir çözüm isteyin.

Turnstile token'ını hangi form alanına yazmalıyım?

Birincil alan cf-turnstile-response'dir; bazı sayfalar aynı token'ı g-recaptcha-response alanında da bekler. Emin değilseniz her iki alanı da doldurun ve sayfanın ayrıca bir callback işlevi çalıştırıp çalıştırmadığını kontrol edin.

Turnstile çözümü için hangi CaptchaAI planı yeterli?

Fiyatlandırma çözüm başına değil, eşzamanlı thread bazlıdır. Tekil ya da düşük hacimli QA akışları için BASIC ($15/ay, 5 thread) genellikle yeter; aynı anda çok sayıda Turnstile çözüyorsanız daha fazla thread'li bir plana geçin. Fiyatlar USD'dir, bu da TL dalgalanmasından bağımsız öngörülebilir bir aylık maliyet sağlar.

Bakiyem var ama ERROR_ZERO_BALANCE alıyorum, neden?

Bu hata bakiyeyle değil, eşzamanlılıkla ilgilidir: planınızdaki tüm thread'ler o an dolu demektir. Açık thread'lerin boşalmasını bekleyin, eşzamanlı istek sayısını düşürün veya thread sayısını artırmak için planınızı yükseltin.

CaptchaAI, Turnstile için proxy destekliyor mu?

Evet. İsteğinize proxy ve proxytype ekleyin. Bağımsız Turnstile widget'ları için proxy isteğe bağlıdır; tam sayfa Cloudflare doğrulama sayfalarında ise önerilir.

Turnstile ile Cloudflare doğrulama akışını nasıl ayırt ederim?

Turnstile, token döndüren gömülü bir widget'tır ve turnstile yöntemini kullanır. Cloudflare doğrulama akışı ise qa_session_cookie çerezi döndüren tam sayfa bir doğrulamadır ve cloudflare_challenge yöntemini kullanır. İkisi de Cloudflare ürünüdür ama entegrasyon modelleri farklıdır.

Turnstile iş akışınızı onarın

Turnstile entegrasyonunuz başarısız oluyorsa sırayla şunları kontrol edin:

1. sitekey'i doğrulayın — data-sitekey'den veya turnstile.render()'den çıkarın
2. pageurl'ü doğrulayın — protokol ve yol dahil tam URL'yi kullanın
3. Token yolunu belirleyin — sayfa cf-turnstile-response, g-recaptcha-response yoksa bir callback mı bekliyor?
4. json=1 kullanın — Turnstile sonuçlarını sorgularken daima JSON yanıtı isteyin
5. Token'ları yeniden kullanmayın — her gönderimde yeni bir çözüm isteyin

CaptchaAI Turnstile çözücüsüyle başlayın, parametrelerinizi API belgeleriyle karşılaştırın ve widget mekaniğini daha derinlemesine anlamak isterseniz Turnstile nasıl çalışır yazısını okuyun.

İlgili Makaleler

• Cloudflare doğrulama akışı ile Turnstile'ı ayırt etme
• GeeTest ve Cloudflare Turnstile karşılaştırması
• Token düzeltmesinden sonra süren Turnstile 403 hatası