Erros e correções do desafio Cloudflare

Se a resolução do Cloudflare Turnstile em staging falha mesmo com a chave de API correta, o motivo quase sempre é o proxy — não a chamada em si. Diferente do reCAPTCHA, o cookie de validação fica preso ao IP que resolveu o desafio: trocar de proxy no meio do caminho invalida tudo. Este guia reúne os erros mais frequentes, da falta de parâmetro ao IP banido, com a causa e a correção de cada um.

Checklist rápido de diagnóstico

Erros de envio na API

ERROR_BAD_PARAMETERS

Causa: faltam parâmetros obrigatórios. Correção: o Cloudflare Turnstile em staging exige estes quatro parâmetros — diferente do Turnstile comum ou do reCAPTCHA, nenhum deles é opcional:

method=turnstile_staging
pageurl=https://example.com
proxy=user:pass@host:port
proxytype=HTTP

ERROR_PROXY_CONNECTION_FAILED

Causa: a CaptchaAI não consegue se conectar pelo seu proxy. Correção: teste o proxy isoladamente com curl -x http://user:pass@host:port https://httpbin.org/ip, confirme que ele suporta HTTPS, verifique se o provedor exige lista de IPs liberada e tente um proxy diferente do mesmo provedor.

ERROR_PROXY_BANNED

Causa: o IP do seu proxy está bloqueado pela Cloudflare. Correção: troque para um egress de rede autorizado ou um proxy de ISP — IPs de datacenter são fortemente sinalizados — e faça a rotação para um IP novo antes de tentar de novo.

ERROR_CAPTCHA_UNSOLVABLE

Causa: o desafio não pôde ser resolvido, mesmo depois de novas tentativas. Correção: o site pode ter mudado a configuração de proteção da Cloudflare, ou o próprio IP do proxy pode estar bloqueado — tente outro proxy, aguarde 5 minutos (a Cloudflare pode estar em modo de segurança reforçada) e confirme que a URL ainda mostra o Cloudflare Turnstile em staging, não outra proteção.

Erros do cookie de validação (cookie_qa_validacao)

Cookie rejeitado — o site continua mostrando o desafio

Causa: incompatibilidade de IP entre a resolução e o uso posterior. Correção: use exatamente o mesmo proxy nas requisições seguintes:

# WRONG — different proxy for solving and requests
solve_proxy = "proxy1.example.com:8080"
request_proxy = "proxy2.example.com:8080"

# CORRECT — same proxy for both
proxy = "user:pass@proxy1.example.com:8080"

# Submit solve with this proxy
response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": API_KEY,
    "method": "turnstile_staging",
    "pageurl": "https://example.com",
    "proxy": proxy,
    "proxytype": "HTTP",
    "json": 1
})

# Use the SAME proxy for page requests
session = requests.Session()
session.cookies.set("cookie_qa_validacao", solved_cookie)
session.proxies = {"https": f"http://{proxy}"}

Cookie rejeitado — User-Agent inconsistente

Causa: o User-Agent da resolução é diferente do usado nas requisições. Correção: reaproveite o agente de usuário retornado na resposta da resolução:

solution = result["request"]

# Extract and reuse the exact user agent
user_agent = solution.get("user_agent")

session = requests.Session()
session.headers["User-Agent"] = user_agent  # Must match exactly
session.cookies.set("cookie_qa_validacao", solution["cookie_qa_validacao"])

Cookie expira antes do esperado

Causa: o cookie_qa_validacao tem um TTL limitado (normalmente de 15 minutos a 24 horas). Correção: anote o horário em que o cookie foi obtido, resolva de novo antes que o TTL expire e implemente a resolução automática ao detectar a página de desafio outra vez:

def make_request(url, session):
    response = session.get(url)
    if "challenge" in response.text.lower() or response.status_code == 403:
        # Cookie expired — re-solve
        new_cookie = solve_turnstile_staging(url, proxy)
        session.cookies.set("cookie_qa_validacao", new_cookie)
        response = session.get(url)
    return response

Caso real: pool de proxy trocando de IP no meio do teste

Uma equipe de QA que roda testes de integração autorizados contra staging.example.com via CI enfrentava falhas intermitentes: a primeira requisição passava, a segunda voltava a mostrar o desafio. A causa era um pool de proxy com IPs de saída rotativos — cada chamada pegava um IP diferente, inclusive entre a resolução e o uso do cookie_qa_validacao. A correção: fixar um proxy dedicado por execução, do início ao fim. Rodando em sa-east-1 (São Paulo) ou na Europa, vale checar se o balanceador de saída troca de IP sem avisar — e manter o teste no escopo autorizado também ajuda na conformidade com LGPD/RGPD.

Erros de tempo limite (timeout)

A resolução demora mais de 5 minutos

Causa: as páginas do Cloudflare Turnstile em staging ficam lentas quando o proxy é lento ou o desafio é complexo. Correção: use um proxy com menor latência, aumente o timeout do polling para 60 tentativas (5 minutos) e confirme que o site realmente tem um Cloudflare Turnstile em staging, não outra proteção.

CAPCHA_NOT_READY não sai do lugar

Causa: a resolução ainda está em andamento. Correção: o Cloudflare Turnstile em staging leva de 20 a 60 segundos — mais tempo que outros tipos —, então consulte o resultado a cada 5 segundos por até 60 tentativas; se ainda não estiver pronto depois de 5 minutos, aborte e tente de novo com outro proxy.

Erros e correções rápidas

• Parâmetro de proxy ausente → ERROR_BAD_PARAMETERS. Inclua sempre o proxy para o Cloudflare Turnstile em staging.
• Proxy de datacenter → ERROR_PROXY_BANNED. Use egress de rede autorizado ou proxy de ISP.
• User-Agent diferente nas requisições → cookie rejeitado. Reaproveite o User-Agent da resolução.
• IP diferente nas requisições → cookie rejeitado. Use o mesmo proxy em todas as requisições.
• Domínio do cookie não configurado → cookie não enviado. Defina o domínio como .example.com (com o ponto no início).
• HTTP em vez de HTTPS → falha de conexão. A Cloudflare exige HTTPS.

Perguntas frequentes

Preciso resolver um novo desafio a cada requisição?

Não. Enquanto o cookie_qa_validacao estiver dentro do TTL, reaproveite o mesmo cookie e o mesmo proxy nas requisições seguintes. Só resolva de novo quando o cookie expirar ou a sessão mudar.

A CaptchaAI aceita proxy SOCKS5 para esse tipo de tarefa?

Sim. Defina proxytype=SOCKS5 e formate o proxy como user:pass@host:port.

ERROR_BAD_PARAMETERS sempre significa que falta o proxy?

Na maioria dos casos, sim. Mas confira também method, pageurl e proxytype — qualquer um ausente gera o mesmo erro.

Como aumento o tempo limite do polling sem travar minha aplicação?

Rode a consulta de resultado em uma tarefa assíncrona ou em segundo plano, em vez de bloquear a thread principal esperando a resposta.

Troquei de IP e o ERROR_CAPTCHA_UNSOLVABLE continua aparecendo — o que fazer?

O IP do proxy provavelmente está sinalizado pela Cloudflare. Rotacione para um novo IP de egress autorizado; se persistir em vários IPs, o site tem uma proteção muito rígida.

Guias relacionados

• Como funciona o Cloudflare Turnstile em staging
• Como resolver o Cloudflare Turnstile em staging pela API
• Como funciona o Cloudflare Turnstile
• Referência de códigos de erro da CaptchaAI