ERROR_PAGEURL: Guia de solução de problemas de incompatibilidade de URL

Se a API respondeu com ERROR_PAGEURL, o pageurl enviado não é idêntico ao URL na barra de endereços no instante em que o CAPTCHA carregou. Os solucionadores validam o token contra o domínio de origem, então um protocolo errado, um subdomínio trocado ou uma rota desatualizada derrubam a tarefa antes de o desafio ser resolvido. Na maioria dos casos, a correção leva menos de cinco minutos assim que você sabe qual URL exata capturar.

O que o erro significa, em uma frase

ERROR_PAGEURL significa que a URL enviada no parâmetro pageurl não é a URL real onde o desafio CAPTCHA foi carregado no navegador. O solucionador valida o token contra esse domínio de origem, e qualquer divergência é suficiente para rejeitar a tarefa.

Causas mais comuns

• Protocolo ausente — enviar example.com em vez de https://example.com.
• Domínio diferente do exibido no navegador — www.example.com no pageurl, mas a página real carrega em example.com.
• Redirecionamento mudou a URL — o formulário estava em /login e o navegador foi levado para /auth/login.
• Rota de SPA divergente da URL do servidor — a rota JS /app/login não bate com a URL real da página.
• Caracteres não codificados — espaços ou símbolos sem encoding no pageurl.
• Iframe de outro domínio — o widget do CAPTCHA vem de um subdomínio diferente do domínio principal.

Checklist de diagnóstico em 5 passos

1. Abra a página no navegador e copie a URL exata da barra de endereços — nunca a URL que você já "sabe de cor".
2. Confirme protocolo e subdomínio: https:// vs. http://, com www. ou sem, contam como domínios diferentes para o solucionador.
3. Se a página redireciona, capture o destino final com get_final_url(), não a URL de entrada.
4. Em SPAs, leia a rota atual exibida no navegador — nunca o endpoint interno que o formulário chama.
5. Rode validate_pageurl() antes de cada chamada à API, para falhar rápido com uma mensagem clara em vez de uma rejeição silenciosa.

Como identificar a URL correta

Use o URL exato da barra de endereços no instante em que o CAPTCHA aparece — nunca o endpoint de API nem a URL de callback.

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

# WRONG — wrong protocol
pageurl = "http://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"

Valide o pageurl antes de enviar

Um helper de validação evita boa parte dos erros antes mesmo de a requisição sair do seu código:

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"

Redirecionamentos: use o destino final

Se a página redireciona antes de exibir o CAPTCHA, o pageurl precisa refletir o destino final, não a URL que você digitou primeiro:

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

Esse padrão resolve a maioria dos casos de "funciona no navegador, falha no script" — a diferença quase sempre é um redirecionamento que o código não seguiu.

SPAs: qual URL usar

Em SPAs, a rota muda sem recarregar a página. Vale o domínio da barra de endereços, não o endpoint interno chamado pelo formulário:

# 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 em iframe: use a URL da página principal

O pageurl continua sendo o da página visível, mesmo quando o widget carrega de um iframe de outro domínio — nunca o src do iframe:

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

Envio correto para a API

Com o URL validado, o envio para o endpoint in.php segue o fluxo padrão:

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')}")

Se status vier 0, o campo request traz o código do erro — é aí que ERROR_PAGEURL aparece quando o problema é o valor enviado.

Um cenário comum em times de QA no Brasil

Times que rodam staging na região sa-east-1 (São Paulo) da AWS costumam ver esse erro quando o CAPTCHA vem de um subdomínio de preview — algo como preview-pr123.staging.example.com — enquanto o pageurl enviado ao endpoint ainda aponta para o domínio principal do ambiente. O sintoma típico: o teste passa localmente, mas falha no pipeline de CI, porque cada build de preview recebe uma URL diferente. A correção é a mesma em qualquer mercado: capturar o pageurl dinamicamente a partir do driver de automação, no momento exato da resolução, nunca fixá-lo como constante no início do script.

Tabela de sintomas e correções

Perguntas frequentes

O que o ERROR_PAGEURL está me dizendo?

Que o pageurl não corresponde à página onde o CAPTCHA carregou. Não é problema de chave de API nem de sitekey — é esse campo que está incorreto ou desatualizado.

O domínio basta, ou preciso do caminho completo?

O domínio é crítico para a validação, mas envie o caminho completo sempre que possível: alguns sites validam a URL inteira, e um pageurl parcial pode gerar rejeição silenciosa.

Copiei o URL certo e o erro continua — por quê?

Geralmente é www vs. não-www ou HTTP vs. HTTPS: parecem o mesmo site para uma pessoa, mas são domínios distintos para o solucionador. Confira exatamente no instante da resolução.

Como capturo o pageurl certo com Selenium ou Playwright?

Leia a URL direto do driver (driver.current_url ou page.url) antes de enviar a tarefa, em vez de fixar o valor no início do script. Evita erros em SPAs.

Guias relacionados

• Como diagnosticar o erro WRONG_GOOGLEKEY
• Validação de parâmetros com BAD_PARAMETERS

Corrija o pageurl e resolva o CAPTCHA agora com a CaptchaAI.