ERROR_PAGEURL: Guía de solución de problemas de falta de coincidencia de URL

Tu tarea llega bien a la API, pero CaptchaAI responde ERROR_PAGEURL y el token nunca se genera. El motivo casi siempre es el mismo: el pageurl que envías no apunta al dominio donde el navegador muestra el CAPTCHA. El servicio valida cada token contra el dominio de origen, así que un protocolo omitido, un www de más o una redirección silenciosa rompen la coincidencia. La solución es directa: envía la URL que ves en la barra de direcciones cuando el CAPTCHA está a la vista.

Por qué aparece ERROR_PAGEURL

Cuál es la URL correcta que debes enviar

Regla: usa la URL que aparece en la barra de direcciones con el CAPTCHA a la vista

Ignora la URL a la que apunta el formulario o la que devuelve tu API interna: lo único que valida el token es la dirección visible en el navegador.

# WRONG — incomplete URL
pageurl = "staging.example.com/qa-login"

# WRONG — wrong protocol
pageurl = "https://staging.example.com/qa-login"

# CORRECT — full URL with protocol
pageurl = "https://staging.example.com/qa-login"

# CORRECT — with www if that's what the page uses
pageurl = "https://www.staging.example.com/qa-login"

Valida el pageurl antes de enviarlo

Un pequeño validador previo evita la mayoría de los ERROR_PAGEURL: exige protocolo, comprueba el dominio y descarta el fragmento (#seccion), que nunca llega al servidor.

from urllib.parse import urlparse


def validate_pageurl(url):
    """Validate pageurl before API submission."""
    parsed = urlparse(url)

    if not parsed.scheme:
        raise ValueError(f"Missing protocol: {url}. Use https://")

    if parsed.scheme not in ("http", "https"):
        raise ValueError(f"Invalid protocol: {parsed.scheme}")

    if not parsed.netloc:
        raise ValueError(f"Missing domain: {url}")

    # Remove fragment (hash) — not sent to server
    clean = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
    if parsed.query:
        clean += f"?{parsed.query}"

    return clean


# Usage
url = validate_pageurl("https://staging.example.com/qa-login#section")
# Returns: "https://staging.example.com/qa-login"

Sigue las redirecciones hasta la URL final

Es un patrón habitual en portales de trámites y de cita previa: escribes el dominio raíz y el servidor te redirige a www.dominio/es/login antes de mostrar el reCAPTCHA. Si envías la URL inicial, el dominio no coincide: sigue la redirección y usa la dirección final.

import requests


def get_final_url(url):
    """Follow redirects to get the actual page URL."""
    resp = requests.get(url, allow_redirects=True, timeout=15)
    return resp.url


# If the login page redirects
original = "https://staging.example.com/qa-login"
final = get_final_url(original)
print(f"Final URL: {final}")
# Use final URL as pageurl

URLs en aplicaciones de una sola página (SPA)

Los SPA cambian la URL con JavaScript sin recargar la página. Lo que cuenta es el dominio donde vive el CAPTCHA, no el endpoint al que envía el formulario:

# For SPAs, use the domain root + the route shown in the address bar
# NOT the API endpoint that the form submits to

# WRONG — API endpoint
pageurl = "https://api.example.com/v1/auth/login"

# CORRECT — the page URL shown in browser
pageurl = "https://staging.example.com/qa-login"

CAPTCHA incrustado en un iframe

Cuando el CAPTCHA se carga dentro de un iframe de otro dominio, no envíes el src del iframe: el pageurl correcto es el de la página principal que el usuario tiene abierta.

# If the CAPTCHA is on the MAIN page
pageurl = "https://example.com/register"  # Main page URL

# If the CAPTCHA is in an IFRAME with a different domain
# Still use the main page URL, not the iframe src
pageurl = "https://example.com/register"
# NOT: "https://captcha-frame.example.com/challenge"

Envío correcto a la API

import requests

# Validate URL first
pageurl = validate_pageurl("https://staging.example.com/qa-login")

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": pageurl,
    "json": 1,
})
result = resp.json()

if result.get("status") == 1:
    print(f"Task ID: {result['request']}")
else:
    print(f"Error: {result.get('request')}")

Tabla de diagnóstico rápido

Preguntas frecuentes

¿ERROR_PAGEURL y WRONG_GOOGLEKEY son el mismo problema?

No. ERROR_PAGEURL indica que la URL de la página no coincide con el dominio del CAPTCHA; WRONG_GOOGLEKEY señala que el sitekey es incorrecto o no corresponde a esa página. Comprueba primero cuál de los dos parámetros estás pasando mal.

¿El pageurl tiene que usar el mismo protocolo que la página?

Sí. Si la página carga bajo https://, el pageurl debe empezar por https://. Mezclar http y https cuenta como un dominio distinto.

¿Necesito la ruta completa o basta con el dominio?

El dominio es lo crítico para validar el token, pero envía la ruta completa siempre que puedas: algunos sitios comprueban la URL entera y una ruta parcial provoca rechazos intermitentes.

¿Qué hago si la página redirige antes de mostrar el CAPTCHA?

Sigue la redirección hasta la URL final y úsala como pageurl; get_final_url() recorre la cadena por ti.

Guías relacionadas

• Diagnóstico de WRONG_GOOGLEKEY
• Validación del error BAD_PARAMETERS

Configuración de navegador reproducible en tu pipeline

Usa exactamente la misma configuración de navegador en QA, staging y CI. Así evitas que un test pase en local y falle en CI sin motivo aparente.

from selenium import webdriver

def make_driver(headless: bool = True) -> webdriver.Chrome:
    options = webdriver.ChromeOptions()
    if headless:
        options.add_argument('--headless=new')
    options.add_argument('--window-size=1280,800')
    options.add_argument('--lang=es-ES')
    return webdriver.Chrome(options=options)

Mantener idénticos el viewport, el idioma y el user-agent en todos los runners reduce la varianza y facilita comparar ejecuciones de tu propio QA.

Cómo encaja CaptchaAI en tu propio flujo

El patrón de integración con CaptchaAI es siempre el mismo, sea cual sea tu framework de pruebas:

1. Tu test detecta el widget de CAPTCHA en una página de tu propia aplicación (formulario de QA, landing de staging, endpoint de preproducción).
2. Tu test envía a CaptchaAI los datos públicos del widget (sitekey, URL de la página, tipo de CAPTCHA).
3. CaptchaAI devuelve un token válido para esa página.
4. Tu test inyecta ese token en el campo correspondiente y envía el formulario.
5. Tu backend verifica el token con el proveedor de CAPTCHA, igual que con un usuario real.

Este flujo se aplica solo a integraciones que tú controlas; no sirve para sortear protecciones de sitios de terceros.

Métricas para detectar regresiones a tiempo

Instrumenta los pasos del CAPTCHA en tus pipelines de QA para detectar regresiones antes de que lleguen a producción:

• Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
• Tasa de éxito por endpoint propio — cuántas verificaciones de backend pasan respecto al total de intentos.
• Distribución de errores — agrupados por código (ERROR_*, tiempos de espera internos, fallos de red).
• Latencia extremo a extremo — incluyendo render de la página, resolución del CAPTCHA y respuesta de tu backend.

Buenas prácticas en tu entorno de QA

• Prueba siempre sobre tu propia aplicación o sobre entornos explícitamente autorizados.
• Mantén una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
• Define tiempos de espera y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes durante una caída.
• Versiona tus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revisa el changelog de tu proveedor de CAPTCHA para anticipar cambios en tu integración.

Envía siempre la URL correcta y resuelve con CaptchaAI.