Erros e solução de problemas da catraca da Cloudflare

A maioria das falhas do Cloudflare Turnstile não são aleatórias. Eles se enquadram em três categorias: erros no estágio de solicitação (seu envio à API é rejeitado), erros no estágio de resultado (falha na pesquisa ou expira) e falhas na validação da página de destino (a API retorna um token válido, mas a página ainda o rejeita).

Os três maiores problemas específicos da catraca são:

1. URL exato da página errado — especialmente nas páginas de desafio da Cloudflare, onde o contexto é mais rigoroso
2. Sitekey errada — capturada do elemento errado ou de uma instância de widget diferente
3. Token aplicado pelo caminho errado — a página espera cf-turnstile-response, um retorno de chamada ou ambos

CaptchaAI resolve catraca com umTaxa de sucesso de 100%em menos de 10 segundos. Quando sua integração falha, o problema quase sempre está nos parâmetros que você envia ou em como aplica o token retornado.

Pontos de falha específicos da catraca

Antes de mergulhar nos códigos de erro, entenda as três coisas que tornam o Turnstile diferente de outros tipos de captcha:

1. O URL exato da página é mais importante

Os tokens da catraca estão fortemente vinculados ao contexto da página. Nas páginas de desafio da Cloudflare (a tela de verificação de página inteira), usar o URL errado — mesmo que seja um caminho ligeiramente diferente — fará com que o token seja rejeitado.

2. Dois caminhos de aplicação de token

O token retornado pode ser aplicado de duas maneiras, e usar o token errado falhará silenciosamente:

3. Os tokens são descartáveis

Um token Turnstile só pode ser verificado uma vez. Se sua automação a enviar duas vezes acidentalmente ou se houver uma condição de corrida, a segunda tentativa falhará.

Erros na fase de solicitação

Isso acontece ao enviar a tarefa para https://ocr.captchaai.com/in.php.

ERROR_WRONG_USER_KEY

Causa: O formato da chave de API está incorreto (deve ter 32 caracteres).

Correção: Verifique a chave decaptchaai.com/api.php.

ERROR_KEY_DOES_NOT_EXIST

Causa: A chave está formatada corretamente, mas não está vinculada a uma conta ativa.

Correção: Verifique seu painel. Certifique-se de que a conta esteja ativa e a chave esteja correta.

ERROR_ZERO_BALANCE

Causa: Não há tópicos gratuitos no seu plano.

Correção: Aguarde a liberação dos threads, diminua a simultaneidade ou atualize.

ERROR_PAGEURL

Causa: O parâmetro pageurl está ausente.

Correção: Adicione o URL completo — protocolo, domínio e caminho:

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

ERROR_BAD_PARAMETERS

Causa: Os parâmetros obrigatórios estão ausentes ou mal formados. Para Cloudflare Turnstile, os parâmetros necessários são:

Opcional, mas útil:

Correção: Verifique se todos os campos obrigatórios estão presentes e digitados corretamente.

Respostas HTML ou 500/502

Causa: Erro temporário no servidor.

Correção: Aguarde de 5 a 10 segundos e tente novamente.

Como encontrar a chave do site da catraca

O sitekey é o parâmetro mais comumente errado. Aqui está onde encontrá-lo:

Opção 1 — o atributo data-sitekey:

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

Opção 2 — uma chamada turnstile.render():

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

Opção 3 — interceptando a chamada de renderização (avançado):

Se a chave do site for carregada dinamicamente, você poderá redefinir turnstile.render antes que o widget seja inicializado para capturar os 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);
};

Erros na fase de resultados

Isso acontece durante a votação de https://ocr.captchaai.com/res.php.

CAPCHA_NOT_READY

Não é um erro. A solução ainda está em andamento. A solução da catraca em CaptchaAI normalmente leva menos de 10 segundos.

Correção: Aguarde 5 segundos e pesquise novamente.

ERROR_WRONG_ID_FORMAT

Causa: O ID do captcha contém caracteres não numéricos.

Correção: Use o ID exato retornado por in.php, sem modificação.

ERROR_WRONG_CAPTCHA_ID

Causa: O ID não corresponde a nenhuma tarefa enviada.

Correção: Verifique se você está pesquisando o ID correto da resposta do envio.

ERROR_EMPTY_ACTION

Causa: O parâmetro action está faltando na sua solicitação de enquete.

Correção: Sempre inclua action=get:

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

Observação: Para Cloudflare Turnstile, sempre use json=1 em sua solicitação de enquete. A resposta JSON pode incluir o user_agent do solucionador, que algumas páginas protegidas pela Cloudflare exigem para uma validação de token bem-sucedida.

ERROR_CAPTCHA_UNSOLVABLE

Causa: A solução falhou — possivelmente uma chave de site errada ou uma configuração de página não suportada.

Correção: verifique a chave do site, atualize a solicitação e tente novamente.

ERROR_INTERNAL_SERVER_ERROR

Causa: Problema no servidor.

Correção: Aguarde 10 segundos e tente novamente.

Falhas na validação da página de destino

Estes são os mais difíceis de depurar porque a API retorna um token com sucesso, mas a página de destino o rejeita.

Falha 1: Token inserido no campo errado

Sintoma: O formulário é enviado, mas a página retorna um erro de validação ou é atualizada.

As páginas da catraca podem esperar o token em diferentes campos:

• cf-turnstile-response — a principal entrada oculta da catraca
• g-recaptcha-response — algumas páginas usam isso como alternativa

Correção: Verifique o formulário da página para ambos os campos. Na automação do 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)

Falha 2: retorno de chamada não acionado

Sintoma: O token está no campo, mas o formulário ainda bloqueia o envio.

Causa: a página usa uma função de retorno de chamada em vez (ou além) do campo oculto. O retorno de chamada lida com lógica adicional, como ativar o botão de envio ou enviar uma solicitação AJAX.

Correção: Encontre e ligue para o retorno de chamada:

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

Falha 3: Contexto exato da página errado

Sintoma: Token rejeitado apesar da chave do site correta e da nova solução.

Causa: O pageurl usado na solicitação da API não corresponde ao contexto real da página. Isso é especialmente comum em:

• Páginas de desafio da Cloudflare — o URL pode incluir parâmetros de consulta ou componentes de caminho importantes
• Aplicativos de página única — o URL visível pode ser diferente do URL que carregou o widget Turnstile

Correção: Use a guia Rede do DevTools para encontrar o URL exato de onde o widget Turnstile é carregado. Use esse URL como pageurl.

Falha 4: Reutilização de token

Sintoma: A primeira solução funciona, as subsequentes falham.

Causa: Os tokens da catraca são descartáveis. Depois de verificado pelo servidor Cloudflare, o token é invalidado.

Correção: Solicite uma nova solução para cada envio de formulário. Não armazene em cache ou reutilize tokens.

Referência rápida de erro para correção

Python: solução completa da catraca

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: solução completa da catraca

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

Cloudflare Turnstile vs Cloudflare Turnstile em staging: qual você está enfrentando?

Se você estiver enfrentando um desafio Cloudflare de página inteira (não um widget incorporado), precisará doSolucionador Cloudflare Turnstile em stagingem vez disso, retorna um cookie cookie_qa_validacao e requer um proxy.

Perguntas frequentes

Por que o Turnstile falha mesmo quando a solicitação parece correta?

As três causas mais comuns: (1) o pageurl está ligeiramente errado — especialmente nas páginas de desafio da Cloudflare, (2) a chave do site foi capturada do elemento errado ou (3) o token está sendo injetado no campo ou caminho de retorno de chamada errado.

Qual é o erro mais comum da catraca?

Usando o URL exato da página errado. Os tokens da catraca estão fortemente vinculados ao contexto da página – até mesmo um caminho diferente ou um parâmetro de consulta ausente pode causar rejeição.

O que significa CAPCHA_NOT_READY?

A solução ainda está em andamento. Aguarde 5 segundos e pesquise novamente. A solução da catraca normalmente é concluída em menos de 10 segundos.

O que devo fazer se a API retornar um token, mas a página ainda o rejeitar?

1. Verifique se pageurl corresponde à página exata onde o widget é carregado.
2. Verifique se a página espera o token em cf-turnstile-response, g-recaptcha-response ou ambos.
3. Verifique se a página usa uma função de retorno de chamada em vez de (ou além de) um campo oculto.
4. Certifique-se de que o token seja usado apenas uma vez – os tokens da catraca são descartáveis.

O CaptchaAI oferece suporte a proxies para Turnstile?

Sim. Adicione proxy e proxytype à sua solicitação. Os proxies são opcionais para widgets Turnstile independentes, mas recomendados nas páginas de desafio da Cloudflare.

Qual é a diferença entre catraca e Cloudflare Turnstile em staging?

Turnstile é um widget incorporado que retorna um token. Cloudflare Turnstile em staging é uma verificação de página inteira que retorna um cookie cookie_qa_validacao. Eles usam diferentes métodos de API e diferentes padrões de integração, embora ambos sejam produtos Cloudflare.

Corrija seu fluxo de trabalho da catraca

Se a integração do seu Turnstile estiver falhando:

1. Verifique a chave do site — Extraia-a de data-sitekey ou turnstile.render()
2. Verifique o pageurl — Use o URL exato, incluindo protocolo e caminho
3. Verifique o caminho do token — A página usa cf-turnstile-response, g-recaptcha-response ou um retorno de chamada?
4. Use json=1 — Sempre use respostas JSON ao pesquisar os resultados do Turnstile
5. Não reutilize tokens — Solicite uma nova solução para cada envio

Comece com oCaptchaAI Solucionador de torniquete, verifique seus parâmetros em relação aoDocumentos da APIe leiaComo funciona o Cloudflare Turnstilese você precisar de informações básicas sobre a mecânica do widget.

Registro de iteração

Resumo do recurso visual

Imagem do herói

• Texto alternativo: Desenvolvedor solucionando erros Cloudflare Turnstile — fluxo de solicitação, envio controlado ao endpoint QA e falhas de validação
• Deve mostrar: Fluxo de solução de problemas técnicos com estágios de erro e caminhos de correção
• Nome do arquivo: cloudflare-turnstile-errors-troubleshooting-hero.png

Visual no artigo 1

• Posicionamento: Após "Erros na fase de resultados"
• Tipo: Árvore de decisão
• Texto alternativo: Árvore de decisão para falhas Cloudflare Turnstile — erros de solicitação versus erros de pesquisa versus rejeição de página
• Nome do arquivo: cloudflare-turnstile-error-decision-tree.png

Visual no artigo 2

• Posicionamento: após "Falhas na validação da página de destino"
• Tipo: Diagrama de causas e soluções
• Texto alternativo: Diagrama mostrando por que os tokens Turnstile foram rejeitados e a correção para cada causa
• Nome do arquivo: cloudflare-turnstile-validation-causes-fixes.png

Artigos relacionados

• Cloudflare Turnstile em staging vs detecção de catraca
• Comparação de Geetest vs Cloudflare Turnstile
• Cloudflare Turnstile 403 Após correção do token