Erros e correções comuns do GeeTest v3

A maioria das falhas do GeeTest v3 se enquadra em um dos três grupos: erros no estágio de solicitação (envio à API), erros no estágio de resultado (pesquisa da resposta) e falhas de validação da página de destino (a API retorna valores, mas a página ainda os rejeita). O maior problema específico do GeeTest é quase sempre o mesmo: um valor challenge obsoleto.

CaptchaAIDocumentos da API GeeTest v3são explícitos: você deve obter um novo valor challenge para cada solicitação de resolução. Assim que o captcha for carregado na página, o antigo desafio se tornará inválido. Isso significa que uma integração GeeTest pode falhar mesmo quando a solicitação parece correta.

Este guia aborda todos os padrões de falha comuns e a solução com menor latência para cada um.

A falha nº 1 do GeeTest: challenge obsoleto

Se há algo a verificar primeiro, é o frescor do desafio.

GeeTest v3 requer dois parâmetros principais:

• gt — a chave pública do site (estática, não muda)
• challenge — a chave do desafio dinâmico (muda a cada carregamento de página)

Por que quebra

O valor challenge é gerado quando o widget GeeTest é inicializado na página. Se você capturá-lo uma vez e reutilizá-lo em várias solicitações de resolução, cada solicitação após a primeira irá:

• ser rejeitado pela API no momento do envio, ou
• produzir um resultado que a página de destino rejeita porque o desafio expirou

Como consertar

Antes de cada solicitação de resolução, inspecione as solicitações de rede da página para encontrar a chamada de API que retorna um novo challenge. Repita essa solicitação para obter um novo valor e envie-o imediatamente para CaptchaAI.

# Pseudocode: fetch a fresh challenge before each solve
import requests

def get_fresh_challenge(target_url):
    """Hit the GeeTest init endpoint to get a new challenge."""
    resp = requests.get(f"{target_url}/geetest/register", timeout=10)
    data = resp.json()
    return data["challenge"], data["gt"]

challenge, gt = get_fresh_challenge("https://example.com")
# Now submit to CaptchaAI immediately — do not delay

Regra geral: Se o tempo entre a captura do challenge e o envio da solicitação de resolução for superior a alguns segundos, atualize-o.

Erros na fase de solicitação

Essas falhas acontecem quando você envia 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. Não adicione caracteres extras ou espaços em branco.

ERROR_KEY_DOES_NOT_EXIST

Causa: a chave de API está formatada corretamente, mas não corresponde a nenhuma conta ativa.

Correção: Faça login no painel CaptchaAI e confirme se sua chave está ativa.

ERROR_ZERO_BALANCE

Causa: Não há tópicos gratuitos disponíveis no seu plano atual.

Correção: Aguarde a liberação dos threads, reduza a simultaneidade ou atualize seu plano.

ERROR_PAGEURL

Causa: O parâmetro pageurl está ausente na solicitação.

Correção: Adicione o URL completo da página onde o widget GeeTest é carregado. Exemplo:

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

ERROR_BAD_PARAMETERS

Causa: Um ou mais campos obrigatórios estão faltando ou estão incorretos. Para GeeTest, os parâmetros necessários são:

Correção: Verifique se gt, challenge e pageurl estão todos presentes e formatados corretamente.

Respostas HTML ou 500/502

Causa: Erro transitório do lado do servidor — não é um problema de parâmetro.

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

Erros na fase de resultados

Essas falhas acontecem quando você pesquisa https://ocr.captchaai.com/res.php.

CAPCHA_NOT_READY

Isso não é um erro. Significa que o captcha ainda está sendo resolvido. GeeTest v3 resolve em CaptchaAI normalmente leva menos de 12 segundos com uma taxa de sucesso de 100%.

Correção: Aguarde 5 segundos e pesquise novamente. Não trate isso como um fracasso.

ERROR_WRONG_ID_FORMAT

Causa: O formato do ID do captcha está errado. Os IDs devem ser apenas numéricos.

Correção: Verifique se você está usando 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á usando o ID correto da resposta do envio. Se você enviou várias tarefas, certifique-se de pesquisar a tarefa certa.

ERROR_EMPTY_ACTION

Causa: O parâmetro action está ausente ou vazio em sua solicitação de enquete.

Correção: Incluir action=get em todas as solicitações de enquete:

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

ERROR_CAPTCHA_UNSOLVABLE

Causa: O desafio não pôde ser resolvido — possivelmente devido a um valor challenge obsoleto ou a uma variante GeeTest não suportada.

Correção: Atualize o valor challenge e tente novamente.

ERROR_INTERNAL_SERVER_ERROR

Causa: Problema no servidor em CaptchaAI.

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

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

Essas são as falhas mais difíceis de depurar porque a API CaptchaAI retorna um resultado válido, mas a página de destino ainda o rejeita.

Quando uma resolução GeeTest v3 é bem-sucedida, a API retorna três valores:

{
  "challenge": "1a2b3456cd67890e12345fab678901c2de",
  "validate": "09fe8d7c6ba54f32e1dcb0a9fedc8765",
  "seccode": "12fe3d4c56789ba01f2e345d6789c012|jordan"
}

Eles devem ser enviados para a página de destino como:

Falha 1: Mapeamento de campo incorreto

Sintoma: a API retorna valores, mas a página de destino os rejeita imediatamente.

Causa: Os valores retornados foram inseridos nos campos errados ou no caminho de solicitação errado.

Correção: Inspecione o tráfego de rede a partir de uma solução manual do GeeTest na página de destino. Encontre a solicitação POST que envia o resultado do GeeTest e corresponda exatamente aos nomes dos seus campos.

Falha 2: challenge obsoleto usado upstream

Sintoma: a API retorna valores, mas a página informa que o desafio expirou ou é inválido.

Cause: The challenge value was captured too early or reused.

Correção: Obtenha um novo challenge imediatamente antes de cada solicitação de resolução. Não armazene em cache ou reutilize-o.

Falha 3: contexto de página errado

Sintoma: A validação falha mesmo com entradas novas.

Causa: O pageurl enviado para CaptchaAI não corresponde à página real onde o widget GeeTest foi carregado.

Correção: Use o URL exato, incluindo protocolo e caminho. Se o widget for carregado via AJAX em uma rota diferente, use a URL dessa rota.

Falha 4: Incompatibilidade entre estrutura de solicitação

Sintoma: Os campos estão corretos, mas o formato da solicitação está errado.

Causa: A página de destino espera os campos GeeTest em um tipo de conteúdo específico (por exemplo, corpo JSON vs. codificado por formulário) ou junto com outros campos de formulário.

Correção: compare sua solicitação de envio com o tráfego de rede de uma solução manual. Combine o tipo de conteúdo, a ordem dos campos e quaisquer campos adicionais.

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

Python: solução completa de GeeTest v3 com novo desafio

import time
import requests

API_KEY = "YOUR_CAPTCHAAI_API_KEY"

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


def get_fresh_challenge(target_url):
    """Fetch a fresh GeeTest challenge from the target page."""
    resp = requests.get(f"{target_url}/api/geetest/register", timeout=10)
    data = resp.json()
    return data["gt"], data["challenge"]


def solve_geetest_v3(api_key, gt, challenge, pageurl):
    """Submit a GeeTest v3 challenge and return the validation package."""

    # Submit
    submit_resp = requests.post(
        SUBMIT_URL,
        data={
            "key": api_key,
            "method": "geetest",
            "gt": gt,
            "challenge": challenge,
            "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
    time.sleep(15)

    # 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("GeeTest v3 solve timed out")


# Usage: always fetch a fresh challenge first
PAGE_URL = "https://staging.example.com/qa-login"
gt, challenge = get_fresh_challenge(PAGE_URL)
result = solve_geetest_v3(API_KEY, gt, challenge, PAGE_URL)
print(f"Result: {result}")

# The result contains: challenge, validate, seccode
# Map them to: geetest_challenge, geetest_validate, geetest_seccode

Node.js: solução completa de GeeTest v3 com novo desafio

const API_KEY = "YOUR_CAPTCHAAI_API_KEY";
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 getFreshChallenge(targetUrl) {
  const resp = await fetch(`${targetUrl}/api/geetest/register`);
  const data = await resp.json();
  return { gt: data.gt, challenge: data.challenge };
}

async function solveGeetestV3(apiKey, gt, challenge, pageurl) {
  // Submit
  const submitResp = await fetch(SUBMIT_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      key: apiKey,
      method: "geetest",
      gt: gt,
      challenge: challenge,
      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}`);

  await sleep(15_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("GeeTest v3 solve timed out");
}

// Usage
const PAGE_URL = "https://staging.example.com/qa-login";

(async () => {
  const { gt, challenge } = await getFreshChallenge(PAGE_URL);
  const result = await solveGeetestV3(API_KEY, gt, challenge, PAGE_URL);
  console.log("Result:", result);
  // Map result fields to: geetest_challenge, geetest_validate, geetest_seccode
})();

Perguntas frequentes

Por que o GeeTest continua falhando mesmo quando a solicitação parece correta?

A causa mais comum é um valor challenge obsoleto. Mesmo que gt e pageurl estejam corretos, um desafio expirado fará com que a API falhe ou a página de destino rejeite os valores retornados. Sempre busque um novo desafio imediatamente antes de cada solicitação de resolução.

Qual é o erro GeeTest v3 mais comum?

Reutilizando um valor challenge que não é mais atualizado. Os documentos CaptchaAI avisam explicitamente que assim que o captcha for carregado na página, o antigo desafio se tornará inválido.

O que significa CAPCHA_NOT_READY?

Isso significa que a solução ainda está em andamento – não é um erro. Aguarde 5 segundos e pesquise res.php novamente. GeeTest v3 resolve em CaptchaAI normalmente leva menos de 12 segundos.

O que devo fazer se a API retornar valores, mas a página ainda os rejeitar?

Verifique três coisas em ordem:

1. Atualidade do desafio — O challenge foi obtido imediatamente antes do envio?
2. Mapeamento de campos — geetest_challenge, geetest_validate e geetest_seccode estão mapeados corretamente para os campos esperados da página de destino?
3. Estrutura da solicitação — A página de destino espera JSON, dados codificados em formulário ou outro formato? Compare com o tráfego de rede de uma solução manual.

Qual a diferença entre GeeTest v3 e reCAPTCHA v2?

GeeTest v3 é um desafio puzzle/slider (não uma caixa de seleção). Requer um parâmetro challenge dinâmico que deve ser atualizado para cada resolução. A API retorna três campos de validação (challenge, validate, seccode) em vez de um único token. Para resolver reCAPTCHA v2, consulteComo resolver reCAPTCHA v2 usando API.

CaptchaAI suporta GeeTest v4?

Este artigo cobre apenas GeeTest v3. Verifique oDocumentos da API CaptchaAIpara os tipos de captcha suportados mais recentes.

Corrija seu fluxo de trabalho GeeTest

Se a integração do GeeTest estiver falhando:

1. Confira o desafio — É novo? Busque um novo imediatamente antes de cada resolução.
2. Verifique os parâmetros — gt, challenge, pageurl devem estar todos corretos.
3. Inspecionar mapeamento de campo — Os challenge, validate e seccode retornados devem ir para os campos corretos.
4. Compare com uma solução manual — Use o DevTools do navegador para capturar a estrutura exata da solicitação de uma solução manual bem-sucedida do GeeTest.

Comece com oSolucionador CaptchaAI GeeTest v3, confirme seus parâmetros em relação aoDocumentos da APIe leiaComo funciona o GeeTest v3 Captchase você precisar de informações básicas sobre o fluxo do desafio.

Registro de iteração

Resumo do recurso visual

Imagem do herói

• Texto alternativo: Solução de problemas do desenvolvedor para erros GeeTest v3 — diagnóstico de falhas de solicitação, pesquisa e validação
• Deve mostrar: Contexto de depuração com estágios de fluxo de erros e pontos de falha
• Nome do arquivo: geetest-v3-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 GeeTest v3 — erros de solicitação versus erros de pesquisa versus falhas de validação
• Nome do arquivo: geetest-v3-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 causas comuns de rejeição de página GeeTest v3 e suas soluções
• Nome do arquivo: geetest-v3-validation-causes-fixes.png

Artigos relacionados

• Resolver Geetest V3 Nodejs
• Resolvendo Geetest V3 Nodejs Captchaai
• Erros e correções comuns de captcha de imagem de grade