Solución de Problemas

Códigos de error CaptchaAI: referencia completa y soluciones

Cloudflare Turnstile Web Scraping
Por Equipo de CaptchaAI en Español
Publicado en Jul 15, 2026
Códigos de error CaptchaAI: referencia completa y soluciones
Imagen destacada no disponible

Esta página documenta todos los códigos de error que puede devolver la API CaptchaAI, organizados por endpoint. Úsala para diagnosticar solicitudes fallidas, implementar manejo de errores adecuado y evitar errores comunes.

La API CaptchaAI tiene dos endpoints:

  • in.php — envía una tarea CAPTCHA (los errores se producen en el momento del envío)
  • res.php — sondea para obtener el resultado (los errores se producen al recuperar los resultados)

Cuando incluye json=1 en su solicitud, los errores regresan como JSON:

{"status": 0, "request": "ERROR_CODE_HERE"}

Sin json=1, los errores regresan como texto sin formato: ERROR_CODE_HERE

Reglas de manejo rápido de errores

Antes de la referencia completa, aquí están las tres reglas que manejan el 90% de los casos:

Patrón de error acción
CAPCHA_NOT_READY Normal: vuelve a realizar la consulta en 5 segundos
Cualquier problema con ERROR_ que comience con el parámetro /format Corrija su solicitud: no vuelva a intentar la misma solicitud
Errores del servidor (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) Reintentar después de 10 segundos con retroceso exponencial

Errores de envío (in.php)

Estos errores ocurren cuando envía una nueva tarea CAPTCHA.

ERROR_WRONG_USER_KEY

Causa: El parámetro key tiene un formato incorrecto. Las claves API CaptchaAI tienen 32 caracteres.

Arreglo:

  1. Comprueba que tu clave tenga exactamente 32 caracteres.
  2. Verifique que no haya espacios adicionales ni saltos de línea.
  3. Copia la clave directamente desde captchaai.com/api.php.

Incorrecto:

{
  "key": "abc123... "
}

Correcto:

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

Causa: La clave API no coincide con ninguna cuenta del sistema.

Arreglo:

  1. Inicia sesión en captchaai.com y copia la clave desde tu panel.
  2. Asegúrese de estar utilizando la clave de cuenta correcta.
  3. Si creó la cuenta recientemente, espere unos minutos hasta que se active la clave.

ERROR_ZERO_BALANCE

Causa: Tu cuenta no tiene hilos disponibles para aceptar la tarea.

Arreglo:

  1. Espere a que se completen las tareas actualmente en ejecución (los subprocesos se liberarán).
  2. Actualice su plan para obtener más hilos simultáneos.
  3. Consulta el saldo de tu cuenta en captchaai.com/api.php.

Esto no siempre es un error de falta de fondos. También puede significar que todos tus hilos están actualmente ocupados. Si tiene un plan de un solo subproceso y se está ejecutando una tarea, los nuevos envíos devolverán este error hasta que se complete la primera tarea.

ERROR_PAGEURL

Causa: El parámetro pageurl falta o está vacío. Este parámetro es necesario para CAPTCHA basados ​​en tokens (reCAPTCHA, Cloudflare Turnstile, GeeTest, etc.).

Solución: Agregue la URL completa de la página donde se carga el CAPTCHA, incluido el protocolo:

Incorrecto:

{
  "pageurl": ""
}

Correcto:

{
  "pageurl": "https://staging.example.com/qa-login"
}

ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY

Causa: El parámetro googlekey (sitekey) está en blanco, tiene un formato incorrecto o falta.

Arreglo:

  1. Vuelva a extraer la clave del sitio del atributo data-sitekey de la página de destino o del parámetro k de la URL de anclaje reCAPTCHA.
  2. Asegúrese de que el valor no esté vacío ni truncado.

Incorrecto:

{
  "googlekey": ""
}

Correcto:

{
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}

ERROR_BAD_TOKEN_OR_PAGEURL

Causa: La combinación de googlekey (clave de sitio) y pageurl no es válida. La clave del sitio no está registrada para la URL de la página determinada.

Causas comunes:

  • El widget reCAPTCHA se carga dentro de un iframe en un subdominio diferente. Está utilizando la URL de la página principal en lugar de la URL del iframe.
  • La clave del sitio pertenece a una página o dominio diferente.
  • La clave del sitio se extrajo de un entorno de desarrollo/staging.

Arreglo:

  1. Si el reCAPTCHA está en un iframe, use la URL src del iframe como pageurl.
  2. Verifique la clave del sitio desde la página de producción en vivo.
  3. Pruebe ambos valores cargando la URL del ancla reCAPTCHA manualmente: https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Causa: La imagen cargada excede el tamaño máximo permitido.

Solución: Comprime o cambia el tamaño de la imagen antes de enviarla. Utilice JPEG para fotografías y PNG para capturas de pantalla.

ERROR_ZERO_CAPTCHA_FILESIZE

Causa: El archivo de imagen es demasiado pequeño (menos de 100 bytes), lo que indica una carga vacía o dañada.

Solución: Verifique que esté enviando datos de imagen reales, no un archivo vacío o una cadena base64 rota.

ERROR_WRONG_FILE_EXTENSION

Causa: El archivo subido tiene una extensión no compatible. Compatible con: jpg, jpeg, png, gif.

Solución: Convierta la imagen a un formato compatible antes de cargarla.

ERROR_IMAGE_TYPE_NOT_SUPPORTED

Causa: El servidor no puede determinar el tipo de imagen a partir del contenido del archivo.

Solución: Convierta a un formato estándar (PNG o JPEG) y asegúrese de que el archivo no esté dañado.

ERROR_UPLOAD

Causa: El servidor no pudo leer el archivo cargado o la carga útil base64.

Arreglo:

  1. Para cargas de archivos: verifique la codificación de datos de su formulario de varias partes.
  2. Para base64: verifique que la cadena base64 esté completa y codificada correctamente.
  3. Pruebe con una imagen en buen estado para descartar daños en el archivo.

ERROR_BAD_PROXY

Causa: El proxy que proporcionaste es inaccesible o el sistema lo ha marcado como incorrecto.

Arreglo:

  1. Pruebe el proxy de forma independiente: ¿puede conectarse al sitio de destino?
  2. Pruebe con un proxy diferente.
  3. Verifique el formato: login:password@IP:PORT o IP:PORT para servidores proxy autenticados por IP.

El uso de proxy debe estar habilitado en su cuenta. Póngase en contacto con el soporte técnico de CaptchaAI si aún no lo ha hecho.

ERROR_BAD_PARAMETERS

Causa: Faltan parámetros obligatorios o tienen tipos de datos incorrectos.

Solución: Consulte la documentación de la API para el tipo de CAPTCHA específico que está resolviendo y verifique que todos los parámetros requeridos estén presentes:

Tipo CAPTCHA Parámetros requeridos
reCAPTCHA v2/v3 key, method=userrecaptcha, googlekey, pageurl
Cloudflare Turnstile key, method=turnstile, sitekey, pageurl
Cloudflare Challenge key, method=cloudflare_challenge, pageurl, proxy, proxytype
GeeTest v3 key, method=geetest, gt, challenge, pageurl
BLS key, method=bls, body, textinstructions
Normal/image key, method=post, file o body

IP_BANNED

Causa: Su IP ha sido prohibida temporalmente después de repetidos intentos fallidos de autenticación.

Solución: Espere aproximadamente 5 minutos y luego vuelva a intentarlo con las credenciales correctas. No siga enviando solicitudes con claves API incorrectas.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

Causa: Se produjo un error transitorio en el lado del servidor.

Solución: Espere 10 segundos y vuelva a intentarlo. Utilice un retroceso exponencial para fallas repetidas:

import time

retry_delay = 10
for attempt in range(5):
    response = submit_captcha()
    if response.get("status") == 1:
        break
    time.sleep(retry_delay)
    retry_delay *= 2  # 10s, 20s, 40s, 80s, 160s

Errores de sondeo (res.php)

Estos errores ocurren cuando verifica el estado de una tarea enviada.

CAPCHA_NOT_READY

Esto no es un error. Significa que la solución aún está en progreso.

Acción: Espere 5 segundos y vuelva a realizar la consulta.

if result.get("request") == "CAPCHA_NOT_READY":
    time.sleep(5)
    continue  # poll again

Guía de tiempos: | Tipo CAPTCHA | Primera consulta después | Intervalo de consulta | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 segundos | 5 segundos | | Cloudflare Turnstile | 15 segundos | 5 segundos | | Cloudflare Challenge | 20 segundos | 5 segundos | | GeeTest v3 | 15 segundos | 5 segundos | | CAPTCHA normal/image | 5 segundos | 5 segundos |

ERROR_CAPTCHA_UNSOLVABLE

Causa: CaptchaAI no pudo resolver el CAPTCHA después de varios intentos.

Razones comunes:

  1. El tipo CAPTCHA no es compatible o los parámetros son incorrectos.
  2. El desafío está corrupto o caducado.
  3. Para soluciones basadas en proxy: el proxy es demasiado lento o inaccesible.
  4. El sitio ha cambiado su implementación CAPTCHA.

Arreglo:

  1. Verifique que sus parámetros (clave del sitio, URL de página, método) sean correctos.
  2. Vuelva a enviarlo con una nueva solicitud.
  3. Si utiliza un proxy, pruebe con uno diferente.
  4. Si el error persiste, es posible que el sitio haya cambiado; vuelva a extraer la clave del sitio y la URL de la página.

No vuelva a intentar el mismo ID de tarea. Envíe una nueva tarea con parámetros nuevos.

ERROR_WRONG_ID_FORMAT

Causa: El ID del captcha debe ser únicamente numérico.

Solución: Verifique que está enviando la identificación exacta devuelta por in.php (solo dígitos, sin caracteres adicionales).

ERROR_WRONG_CAPTCHA_ID

Causa: El ID de la tarea no existe o ha caducado.

Arreglo:

  1. Verifique que esté votando con la identificación devuelta por su envío.
  2. Los ID de las tareas pueden caducar después de períodos prolongados; vuelva a enviarlos si la tarea es muy antigua.

ERROR_EMPTY_ACTION

Causa: El parámetro action falta o está vacío en su solicitud de sondeo.

Solución: Agregue action=get a su solicitud res.php:

params = {
    "key": api_key,
    "action": "get",  # Required
    "id": captcha_id,
    "json": 1,
}

ERROR_PROXY_CONNECTION_FAILED

Causa: El solucionador no pudo conectarse al sitio de destino a través de su proxy.

Arreglo:

  1. Es posible que el proxy esté inactivo temporalmente; pruebe con uno diferente.
  2. Es posible que el sitio de destino esté bloqueando la IP del proxy.
  3. Verifique que el proxy realmente pueda llegar al sitio de destino.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

Estos también pueden aparecer en res.php: la misma causa y solución que los errores de envío anteriores.

Plantilla de manejo de errores

Copie este patrón para un manejo sólido de errores en cualquier idioma:

pitón

import time
import requests

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

# Errors that should not be retried (fix the request first)
NO_RETRY_ERRORS = {
    "ERROR_WRONG_USER_KEY",
    "ERROR_KEY_DOES_NOT_EXIST",
    "ERROR_PAGEURL",
    "ERROR_WRONG_GOOGLEKEY",
    "ERROR_GOOGLEKEY",
    "ERROR_BAD_TOKEN_OR_PAGEURL",
    "ERROR_BAD_PARAMETERS",
    "ERROR_WRONG_FILE_EXTENSION",
    "ERROR_IMAGE_TYPE_NOT_SUPPORTED",
    "IP_BANNED",
}

# Errors that can be retried
RETRY_ERRORS = {
    "ERROR_ZERO_BALANCE",
    "ERROR_SERVER_ERROR",
    "ERROR_INTERNAL_SERVER_ERROR",
    "ERROR_UPLOAD",
}


def solve_captcha(submit_data, max_retries=3, max_polls=60):
    """Submit and solve a CAPTCHA with full error handling."""

    # Submit with retry logic
    for attempt in range(max_retries):
        resp = requests.post(SUBMIT_URL, data={**submit_data, "json": 1}, timeout=30)
        resp.raise_for_status()
        data = resp.json()

        if data.get("status") == 1:
            captcha_id = data["request"]
            break

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

        if error in NO_RETRY_ERRORS:
            raise ValueError(f"Fatal error (fix request): {error}")

        if error in RETRY_ERRORS and attempt < max_retries - 1:
            time.sleep(10 * (2 ** attempt))
            continue

        raise RuntimeError(f"Submit failed: {error}")
    else:
        raise RuntimeError("Submit failed after max retries")

    # Poll for result
    time.sleep(15)

    for _ in range(max_polls):
        resp = requests.get(
            RESULT_URL,
            params={"key": API_KEY, "action": "get", "id": captcha_id, "json": 1},
            timeout=30,
        )
        data = resp.json()

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

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

        error = data.get("request", "UNKNOWN")
        if error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable — resubmit with fresh parameters")

        raise RuntimeError(f"Poll error: {error}")

    raise TimeoutError("Solve timed out")

Nodo.js

const NO_RETRY_ERRORS = new Set([
  "ERROR_WRONG_USER_KEY",
  "ERROR_KEY_DOES_NOT_EXIST",
  "ERROR_PAGEURL",
  "ERROR_WRONG_GOOGLEKEY",
  "ERROR_BAD_TOKEN_OR_PAGEURL",
  "ERROR_BAD_PARAMETERS",
  "IP_BANNED",
]);

async function solveCaptcha(submitData, maxRetries = 3, maxPolls = 60) {
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

  // Submit with retry
  let captchaId;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch("https://ocr.captchaai.com/in.php", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ ...submitData, json: "1" }),
    });
    const data = await resp.json();

    if (data.status === 1) {
      captchaId = data.request;
      break;
    }

    if (NO_RETRY_ERRORS.has(data.request)) {
      throw new Error(`Fatal error: ${data.request}`);
    }

    if (attempt < maxRetries - 1) {
      await sleep(10_000 * 2 ** attempt);
      continue;
    }

    throw new Error(`Submit failed: ${data.request}`);
  }

  // Poll for result
  await sleep(15_000);

  for (let i = 0; i < maxPolls; i++) {
    const resp = await fetch(
      `https://ocr.captchaai.com/res.php?${new URLSearchParams({
        key: submitData.key,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );
    const data = await resp.json();

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

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

    throw new Error(`Poll error: ${data.request}`);
  }

  throw new Error("Solve timed out");
}

Preguntas frecuentes

¿CAPCHA_NOT_READY es un error?

No. Significa que la solución aún está en progreso. Espere 5 segundos y vuelva a sondear. Esto es normal para todos los tipos de CAPTCHA.

¿Qué debo hacer cuando obtenga ERROR_CAPTCHA_UNSOLVABLE?

Envíe una nueva tarea con parámetros nuevos. No vuelva a intentar el mismo ID de tarea. Si el error ocurre repetidamente, verifique que la clave del sitio y la URL de la página sean correctas y que el tipo CAPTCHA sea compatible.

¿Cómo sé si un error se puede volver a intentar?

Los errores del parámetro /format (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, etc.) no se pueden volver a intentar; primero corrija la solicitud. Los errores del servidor (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) se pueden volver a intentar con un retroceso exponencial. ERROR_ZERO_BALANCE se puede volver a intentar después de esperar a que se liberen los subprocesos.

¿Por qué obtengo ERROR_BAD_PROXY por Cloudflare Challenge?

Cloudflare Challenge requiere un proxy que funcione. El proxy debe poder llegar al sitio de destino. Pruébelo de forma independiente y luego pruebe con un proxy diferente si falla. Asegúrese también de que el uso de proxy esté habilitado en su cuenta CaptchaAI.

¿Dónde encuentro mi clave API?

Inicia sesión en captchaai.com y ve a captchaai.com/api.php. Tu clave API de 32 caracteres aparece en el panel.

Guías relacionadas

  • CaptchaAI Inicio rápido— haz que tu primera solución funcione
  • Cómo resolver reCAPTCHA v2 usando API— tutorial completo de reCAPTCHA v2
  • Cómo resolver Cloudflare Challenge usando API— solución de Cloudflare que requiere proxy
  • Errores comunes de resolución de reCAPTCHA v2— Solución de problemas específicos de reCAPTCHA
Los comentarios están deshabilitados para este artículo.