Errores y solución de problemas de Cloudflare Turnstile

La mayoría de los fallos de Cloudflare Turnstile no son aleatorios. Se dividen en tres categorías: errores en la etapa de solicitud (se rechaza su envío a la API), errores en la etapa de resultados (el sondeo falla o se agota el tiempo de espera) y fallas de validación de la página de destino (la API devuelve un token válido pero la página aún lo rechaza).

Los tres mayores problemas específicos de Turnstile son:

1. URL de página exacta incorrecta, especialmente en las páginas de desafío de Cloudflare, donde el contexto es más estricto
2. Clave de sitio incorrecta: capturada desde el elemento incorrecto o una instancia de widget diferente
3. Token aplicado por la ruta incorrecta: la página espera cf-turnstile-response, un callback, o ambos.

CaptchaAI resuelve Turnstile con una tasa de éxito del 100% en menos de 10 segundos. Cuando tu integración falla, el problema casi siempre está en los parámetros que envías o en cómo aplicas el token devuelto.

Puntos de fallo específicos de Turnstile

Antes de profundizar en los códigos de error, entiende las tres cosas que diferencian a Turnstile de otros tipos de captcha:

1. La URL exacta de la página importa más

Los tokens de Turnstile están estrechamente vinculados al contexto de la página. En las páginas de challenge de Cloudflare (la pantalla de verificación de página completa), usar la URL incorrecta (incluso una ruta ligeramente diferente) hará que se rechace el token.

2. Dos rutas de aplicación simbólicas

El token devuelto se puede aplicar de dos maneras, y usar el incorrecto fallará silenciosamente:

3. Los tokens son de un solo uso

Una ficha de Turnstile solo se puede verificar una vez. Si su automatización lo envía accidentalmente dos veces, o si hay una condición de carrera, el segundo intento fallará.

Errores en la etapa de solicitud

Esto sucede al enviar la tarea a https://ocr.captchaai.com/in.php.

ERROR_WRONG_USER_KEY

Causa: El formato de la clave API es incorrecto (debe tener 32 caracteres).

Solución: Verifica la clave en captchaai.com/api.php.

ERROR_KEY_DOES_NOT_EXIST

Causa: La clave tiene el formato correcto pero no está vinculada a una cuenta activa.

Solución: Consulta tu panel de control. Asegúrese de que la cuenta esté activa y que la clave sea correcta.

ERROR_ZERO_BALANCE

Causa: No hay hilos gratuitos en tu plan.

Solución: Espere a que los subprocesos se liberen, reduzcan la simultaneidad o actualicen.

ERROR_PAGEURL

Causa: Falta el parámetro pageurl.

Solución: Agregue la URL completa: protocolo, dominio y ruta:

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

ERROR_BAD_PARAMETERS

Causa: Faltan parámetros obligatorios o están mal formados. Para Turnstile, los parámetros requeridos son:

Opcional pero útil:

Solución: Verifique que todos los campos obligatorios estén presentes y escritos correctamente.

Respuestas HTML o 500/502

Causa: Error transitorio del lado del servidor.

Solución: Espere de 5 a 10 segundos y vuelva a intentarlo.

Cómo encontrar la clave del sitio Turnstile

La clave del sitio es el parámetro incorrecto más común. Aquí es donde encontrarlo:

Opción 1: el atributo data-sitekey:

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

Opción 2: una llamada turnstile.render():

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

Opción 3: interceptar la llamada de renderizado (avanzado):

Si la clave del sitio se carga dinámicamente, puede redefinir turnstile.render antes de que el widget se inicialice para capturar los parámetros:

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

Errores en la etapa de resultados

Esto sucede al sondear https://ocr.captchaai.com/res.php.

CAPCHA_NOT_READY

No es un error. La resolución aún está en progreso. Turnstile en CaptchaAI suele resolverse en menos de 10 segundos.

Solución: Espere 5 segundos y vuelva a sondear.

ERROR_WRONG_ID_FORMAT

Causa: El ID del captcha contiene caracteres no numéricos.

Solución: Utilice el ID exacto devuelto por in.php, sin modificar.

ERROR_WRONG_CAPTCHA_ID

Causa: El ID no coincide con ninguna tarea enviada.

Solución: Verifique que esté sondeando el ID correcto de la respuesta de envío.

ERROR_EMPTY_ACTION

Causa: Falta el parámetro action en su solicitud de consulta.

Solución: Incluya siempre action=get:

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

Nota: Para Turnstile, utilice siempre json=1 en su solicitud de consulta. La respuesta JSON puede incluir el user_agent del solucionador, que algunas páginas protegidas por Cloudflare requieren para una validación exitosa del token.

ERROR_CAPTCHA_UNSOLVABLE

Causa: La solución falló: posiblemente una clave de sitio incorrecta o una configuración de página no compatible.

Solución: Verifique la clave del sitio, actualice la solicitud y vuelva a intentarlo.

ERROR_INTERNAL_SERVER_ERROR

Causa: Problema del lado del servidor.

Solución: Espere 10 segundos y vuelva a intentarlo.

Errores de validación de la página de destino

Estos son los más difíciles de depurar porque la API devuelve un token correctamente, pero la página de destino lo rechaza.

Fallo 1: token insertado en el campo incorrecto

Síntoma: El formulario se envía pero la página devuelve un error de validación o se actualiza.

Las páginas de torniquete pueden esperar el token en diferentes campos:

• cf-turnstile-response: la entrada oculta principal del torniquete
• g-recaptcha-response: algunas páginas utilizan esto como alternativa

Solución: Verifique el formulario de la página para ambos campos. En la automatización del navegador:

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

Fallo 2: callback no activado

Síntoma: El token está en el campo, pero el formulario sigue bloqueando el envío.

Causa: La página usa una función callback en lugar de (o además de) el campo oculto. El callback maneja lógica adicional como habilitar el botón de envío o enviar una solicitud AJAX.

Solución: Busca y llama al callback:

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

Fallo 3: contexto de página exacto incorrecto

Síntoma: Token rechazado a pesar de la clave del sitio correcta y la nueva solución.

Causa: El pageurl utilizado en la solicitud de API no coincide con el contexto real de la página. Esto es especialmente común en:

• Páginas de desafío de Cloudflare: la URL puede incluir parámetros de consulta o componentes de ruta que sean importantes
• Aplicaciones de una sola página: la URL visible puede diferir de la URL que cargó el widget Turnstile

Solución: Utilice la pestaña Red de DevTools para encontrar la URL exacta desde la que se carga el widget Turnstile. Utilice esa URL como pageurl.

Fallo 4: reutilización de tokens

Síntoma: La primera solución funciona, las siguientes fallan.

Causa: Las fichas de torniquete son de un solo uso. Una vez verificado por el servidor de Cloudflare, el token queda invalidado.

Solución: Solicite una nueva solución para cada envío de formulario. No almacene en caché ni reutilice tokens.

Referencia rápida para corregir errores

Python: solución completa de torniquete

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: solución completa de torniquete

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

Turnstile vs Cloudflare Challenge: ¿a cuál te enfrentas?

Si estás enfrentando un challenge de Cloudflare de página completa (no un widget integrado), necesitas el Solucionador de Cloudflare Challenge: devuelve una cookie qa_validation_cookie y requiere un proxy.

Preguntas frecuentes

¿Por qué falla Turnstile incluso cuando la solicitud parece correcta?

Las tres causas más comunes: (1) el pageurl es ligeramente incorrecto, especialmente en las páginas de desafío de Cloudflare, (2) la clave del sitio se capturó del elemento incorrecto o (3) el token se está inyectando en el campo o ruta de devolución de llamada incorrectos.

¿Cuál es el error de torniquete más común?

Usar la URL de la página exacta incorrecta. Los tokens de torniquete están estrechamente vinculados al contexto de la página; incluso una ruta diferente o un parámetro de consulta faltante pueden provocar un rechazo.

¿Qué significa CAPCHA_NOT_READY?

La solución aún está en proceso. Espere 5 segundos y vuelva a sondear. Las soluciones de torniquete normalmente se completan en menos de 10 segundos.

¿Qué debo hacer si la API devuelve un token pero la página aún lo rechaza?

1. Verifique que pageurl coincida con la página exacta donde se carga el widget.
2. Compruebe si la página espera el token en cf-turnstile-response, g-recaptcha-response o ambos.
3. Compruebe si la página utiliza una función de devolución de llamada en lugar de (o además de) un campo oculto.
4. Asegúrese de que la ficha se use solo una vez: las fichas de torniquete son de un solo uso.

¿CaptchaAI admite proxies para Turnstile?

Sí. Agregue proxy y proxytype a su solicitud. Los proxies son opcionales para los widgets independientes de Turnstile, pero se recomiendan en las páginas de desafíos de Cloudflare.

¿Cuál es la diferencia entre torniquete y Cloudflare Challenge?

Turnstile es un widget integrado que devuelve un token. Cloudflare Challenge es una verificación de página completa que devuelve una cookie qa_validation_cookie. Utilizan diferentes métodos API y diferentes patrones de integración, aunque ambos son productos de Cloudflare.

Arregla tu flujo de trabajo de Turnstile

Si su integración de Turnstile falla:

1. Verifique la clave del sitio: extráigala de data-sitekey o turnstile.render()
2. Verifique la URL de la página: utilice la URL exacta, incluido el protocolo y la ruta.
3. Verifique la ruta del token: ¿la página utiliza cf-turnstile-response, g-recaptcha-response o una devolución de llamada?
4. Utilice json=1: utilice siempre respuestas JSON al sondear los resultados de Turnstile
5. No reutilice tokens: solicite una solución nueva para cada envío

Comience con elCaptchaAI Solucionador de torniquetes, verifique sus parámetros con losDocumentos APIy leerCómo funciona Cloudflare Turnstilesi necesita información sobre la mecánica del widget.

Registro de iteración

Resumen de activos visuales

Imagen de héroe

• Texto alternativo: El desarrollador soluciona errores Cloudflare Turnstile: flujo de solicitudes, inyección de token y fallas de validación
• Debe mostrar: Flujo de solución de problemas técnicos con etapas de error y rutas de solución
• Nombre de archivo: cloudflare-turnstile-errors-troubleshooting-hero.png

Visual 1 en el artículo

• Ubicación: Después de "Errores en la etapa de resultados"
• Tipo: Árbol de decisión
• Texto alternativo: Árbol de decisión para fallas de Cloudflare Turnstile: errores de solicitud versus errores de sondeo versus rechazo de página
• Nombre de archivo: cloudflare-turnstile-error-decision-tree.png

Visual 2 en el artículo

• Ubicación: Después de "Errores de validación de la página de destino"
• Tipo: Diagrama de causas y soluciones
• Texto alternativo: Diagrama que muestra por qué se rechazan los tokens Turnstile y la solución para cada causa.
• Nombre de archivo: cloudflare-turnstile-validation-causes-fixes.png

Artículos relacionados

• Cloudflare Challenge vs Turnstile: cómo detectar
• Cloudflare Turnstile 403 después del token: solución
• Cómo resolver Cloudflare Turnstile usando API