Erreurs Cloudflare Turnstile et dépannage

La plupart des échecs de Cloudflare Turnstile ne sont pas aléatoires. Elles se répartissent en trois catégories : les erreurs au stade de la demande (votre soumission à l'API est rejetée), les erreurs au stade du résultat (l'interrogation échoue ou expire) et les échecs de validation de la page cible (l'API renvoie un jeton valide mais la page le rejette toujours).

Les trois plus gros problèmes spécifiques aux tourniquets sont :

1. URL de page exacte erronée — en particulier sur les pages de défi Cloudflare, où le contexte est plus strict
2. Mauvais sitekey — capturé à partir du mauvais élément ou d'une autre instance de widget
3. Jeton appliqué via le mauvais chemin — la page attend cf-turnstile-response, un rappel ou les deux

CaptchaAI résout le tourniquet avec un100% de taux de réussiteen moins de 10 secondes. Lorsque votre intégration échoue, le problème réside presque toujours dans les paramètres que vous envoyez ou dans la manière dont vous appliquez le jeton renvoyé.

Points de défaillance spécifiques aux tourniquets

Avant de plonger dans les codes d'erreur, comprenez les trois choses qui différencient Turnstile des autres types de captcha :

1. L'URL exacte de la page compte davantage

Les jetons tourniquets sont étroitement liés au contexte de la page. Sur les pages de défi Cloudflare (l'écran de vérification pleine page), l'utilisation d'une mauvaise URL (même un chemin légèrement différent) entraînera le rejet du jeton.

2. Deux chemins d'application de jetons

Le jeton renvoyé peut être appliqué de deux manières, et l’utilisation du mauvais jeton échouera silencieusement :

3. Les jetons sont à usage unique

Un jeton Turnstile ne peut être vérifié qu’une seule fois. Si votre automatisation le soumet accidentellement deux fois, ou s'il existe une condition de concurrence critique, la deuxième tentative échouera.

Erreurs au stade de la demande

Cela se produit lors de la soumission de la tâche à https://ocr.captchaai.com/in.php.

ERROR_WRONG_USER_KEY

Cause : Le format de la clé API est incorrect (doit contenir 32 caractères).

Correction : Vérifiez la clé decaptchaai.com/api.php.

ERROR_KEY_DOES_NOT_EXIST

Cause : La clé est correctement formatée mais n'est pas liée à un compte actif.

Correction : Vérifiez votre tableau de bord. Assurez-vous que le compte est actif et que la clé est correcte.

ERROR_ZERO_BALANCE

Cause : Aucune discussion gratuite sur votre forfait.

Correction : Attendez que les threads se libèrent, réduisent la simultanéité ou effectuent une mise à niveau.

ERROR_PAGEURL

Cause : Le paramètre pageurl est manquant.

Correction : Ajoutez l'URL complète (protocole, domaine et chemin) :

pageurl=https://example.com/login

ERROR_BAD_PARAMETERS

Cause : Les paramètres obligatoires sont manquants ou mal formés. Pour Turnstile, les paramètres requis sont :

Facultatif mais utile :

Correction : Vérifiez que tous les champs obligatoires sont présents et correctement saisis.

Réponses HTML ou 500/502

Cause : Erreur transitoire côté serveur.

Correction : Attendez 5 à 10 secondes, puis réessayez.

Comment trouver la clé du site Turnstile

La clé de site est le paramètre le plus souvent erroné. Voici où le trouver :

Option 1 — l'attribut data-sitekey :

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

Option 2 — un appel turnstile.render() :

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

Option 3 — intercepter l'appel de rendu (avancé) :

Si la clé de site est chargée dynamiquement, vous pouvez redéfinir turnstile.render avant que le widget ne s'initialise pour capturer les paramètres :

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

Erreurs au stade du résultat

Cela se produit lors de l'interrogation de https://ocr.captchaai.com/res.php.

CAPCHA_NOT_READY

Il ne s'agit pas d'une erreur. La résolution est toujours en cours. Les résolutions de tourniquet chez CaptchaAI prennent généralement moins de 10 secondes.

Correction : Attendez 5 secondes et interrogez à nouveau.

ERROR_WRONG_ID_FORMAT

Cause : L'ID captcha contient des caractères non numériques.

Correction : Utilisez l'ID exact renvoyé par in.php, non modifié.

ERROR_WRONG_CAPTCHA_ID

Cause : L'ID ne correspond à aucune tâche soumise.

Correction : Vérifiez que vous interrogez le bon identifiant à partir de la réponse à l'envoi.

ERROR_EMPTY_ACTION

Cause : Le paramètre action est manquant dans votre demande d'interrogation.

Correction : Incluez toujours action=get :

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

Remarque : Pour Turnstile, utilisez toujours json=1 dans votre demande de sondage. La réponse JSON peut inclure le user_agent du solveur, dont certaines pages protégées par Cloudflare ont besoin pour réussir la validation du jeton.

ERROR_CAPTCHA_UNSOLVABLE

Cause : La résolution a échoué : il est possible qu'une clé de site soit incorrecte ou une configuration de page non prise en charge.

Correction : Vérifiez la clé du site, actualisez la demande et réessayez.

ERROR_INTERNAL_SERVER_ERROR

Cause : Problème côté serveur.

Correction : Attendez 10 secondes et réessayez.

Échecs de validation de la page cible

Ce sont les plus difficiles à déboguer car l'API renvoie un jeton avec succès, mais la page cible le rejette.

Échec 1 : jeton inséré dans le mauvais champ

Symptôme : Le formulaire est soumis mais la page renvoie une erreur de validation ou s'actualise.

Les pages du tourniquet peuvent s'attendre au jeton dans différents champs :

• cf-turnstile-response — l'entrée cachée principale du tourniquet
• g-recaptcha-response — certaines pages l'utilisent comme solution de secours

Correction : Vérifiez le formulaire de la page pour les deux champs. Dans l'automatisation du navigateur :

# 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)

Échec 2 : rappel non déclenché

Symptôme : Le jeton est dans le champ, mais le formulaire bloque toujours la soumission.

Cause : La page utilise une fonction de rappel à la place (ou en plus) du champ masqué. Le rappel gère une logique supplémentaire comme l'activation du bouton de soumission ou l'envoi d'une requête AJAX.

Correction : Recherchez et rappelez le rappel :

// 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

Échec 3 : contexte de page exact incorrect

Symptôme : Jeton rejeté malgré une clé de site correcte et une nouvelle solution.

Cause : Le pageurl utilisé dans la requête API ne correspond pas au contexte réel de la page. Ceci est particulièrement fréquent sur :

• Pages de défi Cloudflare : l'URL peut inclure des paramètres de requête ou des composants de chemin importants
• Applications d'une seule page — l'URL visible peut différer de l'URL qui a chargé le widget Turnstile

Correction : Utilisez l'onglet Réseau DevTools pour trouver l'URL exacte à partir de laquelle le widget Turnstile est chargé. Utilisez cette URL comme pageurl.

Échec 4 : réutilisation des jetons

Symptôme : La première résolution fonctionne, les suivantes échouent.

Cause : Les jetons tourniquet sont à usage unique. Une fois vérifié par le serveur de Cloudflare, le jeton est invalidé.

Correction : Demandez une nouvelle résolution pour chaque envoi de formulaire. Ne mettez pas en cache et ne réutilisez pas les jetons.

Référence rapide pour corriger les erreurs

Python : résolution complète du tourniquet

import time
import requests

API_KEY = "YOUR_CAPTCHAAI_API_KEY"
SITEKEY = "0x4AAAAAAAB1example"
PAGE_URL = "https://example.com/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 : résolution complète du tourniquet

const API_KEY = "YOUR_CAPTCHAAI_API_KEY";
const SITEKEY = "0x4AAAAAAAB1example";
const PAGE_URL = "https://example.com/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);

Turnstile vs Cloudflare Challenge : à qui faites-vous face ?

Si vous relevez un défi Cloudflare pleine page (et non un widget intégré), vous avez besoin duSolveur Cloudflare Challengeà la place, qui renvoie un cookie cf_clearance et nécessite un proxy.

FAQ

Pourquoi Turnstile échoue-t-il même lorsque la demande semble correcte ?

Les trois causes les plus courantes : (1) le pageurl est légèrement erroné, en particulier sur les pages de défi Cloudflare, (2) la clé du site a été capturée à partir du mauvais élément, ou (3) le jeton est injecté dans le mauvais champ ou chemin de rappel.

Quelle est l’erreur de tourniquet la plus courante ?

Utiliser une mauvaise URL de page exacte. Les jetons Turnstile sont étroitement liés au contexte de la page : même un chemin différent ou un paramètre de requête manquant peut entraîner un rejet.

Que signifie CAPCHA_NOT_READY ?

La résolution est toujours en cours. Attendez 5 secondes et interrogez à nouveau. Les résolutions du tourniquet se terminent généralement en moins de 10 secondes.

Que dois-je faire si l'API renvoie un jeton mais que la page le rejette toujours ?

1. Vérifiez que le pageurl correspond à la page exacte sur laquelle le widget se charge.
2. Vérifiez si la page attend le jeton dans cf-turnstile-response, g-recaptcha-response ou les deux.
3. Vérifiez si la page utilise une fonction de rappel au lieu (ou en plus) d'un champ masqué.
4. Assurez-vous que le jeton n’est utilisé qu’une seule fois – les jetons tourniquets sont à usage unique.

CaptchaAI prend-il en charge les proxys pour Turnstile ?

Oui. Ajoutez proxy et proxytype à votre demande. Les proxys sont facultatifs pour les widgets Turnstile autonomes, mais recommandés sur les pages de défi Cloudflare.

Quelle est la différence entre le tourniquet et Cloudflare Challenge ?

Turnstile est un widget intégré qui renvoie un jeton. Cloudflare Challenge est une vérification pleine page qui renvoie un cookie cf_clearance. Ils utilisent différentes méthodes API et différents modèles d'intégration, bien que les deux soient des produits Cloudflare.

Réparez votre flux de travail Turnstile

Si votre intégration Turnstile échoue :

1. Vérifiez la clé du site — Extrayez-la de data-sitekey ou turnstile.render()
2. Vérifiez l'URL de la page : utilisez l'URL exacte, y compris le protocole et le chemin.
3. Vérifiez le chemin du jeton — La page utilise-t-elle cf-turnstile-response, g-recaptcha-response ou un rappel ?
4. Utilisez json=1 — Utilisez toujours les réponses JSON lors de l'interrogation des résultats du tourniquet
5. Ne réutilisez pas les jetons — Demandez une nouvelle solution pour chaque soumission

Commencez par leCaptchaAI Solveur de tourniquet, vérifiez vos paramètres par rapport auDocuments sur l'API, et lisComment fonctionne Cloudflare Turnstilesi vous avez besoin d'informations sur la mécanique des widgets.

Journal d'itération

Brief sur les atouts visuels

Image de héros

• Texte alternatif : Dépannage des erreurs Cloudflare Turnstile par le développeur : échecs du flux de requêtes, de l'injection de jetons et de la validation
• Doit montrer : Flux de dépannage technique avec étapes d'erreur et chemins de correction
• Nom du fichier : cloudflare-turnstile-errors-troubleshooting-hero.png

Visuel 1 dans l'article

• Placement : Après "Erreurs à l'étape de résultat"
• Type : Arbre de décision
• Texte alternatif : Arbre de décision pour les échecs de Cloudflare Turnstile : erreurs de demande, erreurs d'interrogation et rejet de page
• Nom du fichier : cloudflare-turnstile-error-décision-tree.png

Visuel 2 dans l'article

• Placement : Après les « Échecs de validation de la page cible »
• Type : Diagramme des causes et des solutions
• Texte alternatif : Diagramme montrant pourquoi les jetons Turnstile sont rejetés et le correctif pour chaque cause
• Nom du fichier : cloudflare-turnstile-validation-causes-fixes.png

Articles connexes

• Cloudflare Challenge vs détection de tourniquet
• Comparaison Geetest et Cloudflare Turnstile
• Cloudflare Turnstile 403 après la correction du jeton