Solução de Problemas

Códigos de erro CaptchaAI: referência completa e correções

Cloudflare Turnstile
Por Equipe CaptchaAI Brasil
Publicado em May 19, 2026
Códigos de erro CaptchaAI: referência completa e correções
Imagem em destaque indisponível

Esta página documenta todos os códigos de erro que a API CaptchaAI pode retornar, organizados por endpoint. Use-o para diagnosticar solicitações com falha, implementar o tratamento adequado de erros e evitar erros comuns.

A API CaptchaAI possui dois endpoints:

  • in.php — envie uma tarefa CAPTCHA (ocorrem erros no momento do envio)
  • res.php — pesquisa para o resultado (ocorrem erros durante a recuperação dos resultados)

Quando você inclui json=1 em sua solicitação, os erros retornam como JSON:

{"status": 0, "request": "ERROR_CODE_HERE"}

Sem json=1, os erros retornam como texto simples: ERROR_CODE_HERE

Regras rápidas de tratamento de erros

Antes da referência completa, aqui estão as três regras que tratam de 90% dos casos:

Padrão de erro Ação
CAPCHA_NOT_READY Normal — enquete novamente em 5 segundos
Qualquer ERROR_ começando com o parâmetro /format apresenta problemas Corrija sua solicitação – não tente novamente a mesma solicitação
Erros de servidor (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) Tente novamente após 10 segundos com espera exponencial

Enviar erros (in.php)

Esses erros ocorrem quando você envia uma nova tarefa CAPTCHA.

ERROR_WRONG_USER_KEY

Causa: O parâmetro key tem um formato incorreto. As chaves da API CaptchaAI têm 32 caracteres.

Correção:

  1. Verifique se sua chave tem exatamente 32 caracteres.
  2. Verifique se não há espaços extras ou quebras de linha.
  3. Copie a chave diretamente decaptchaai.com/api.php.
{
  "key": "abc123... "
}

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

Causa: A chave de API não corresponde a nenhuma conta no sistema.

Correção:

  1. Faça logincaptchaai.come copie a chave do seu painel.
  2. Certifique-se de usar a chave da conta correta.
  3. Se você criou a conta recentemente, aguarde alguns minutos para que a chave seja ativada.

ERROR_ZERO_BALANCE

Causa: Sua conta não tem tópicos disponíveis para aceitar a tarefa.

Correção:

  1. Aguarde a conclusão das tarefas em execução (os threads serão liberados).
  2. Atualize seu plano para mais threads simultâneos.
  3. Verifique o saldo da sua conta emcaptchaai.com/api.php.

Isso nem sempre é um erro de falta de fundos. Também pode significar que todos os seus tópicos estão ocupados no momento. Se você tiver um plano de thread único e uma tarefa estiver em execução, novos envios retornarão esse erro até que a primeira tarefa seja concluída.

ERROR_PAGEURL

Causa: O parâmetro pageurl está ausente ou vazio. Este parâmetro é necessário para CAPTCHAs baseados em token (reCAPTCHA, Cloudflare Turnstile, GeeTest, etc.).

Correção: Adicione o URL completo da página onde o CAPTCHA é carregado, incluindo o protocolo:

{
  "pageurl": ""
}

{
  "pageurl": "https://staging.example.com/qa-login"
}

ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY

Causa: O parâmetro googlekey (sitekey) está em branco, malformado ou ausente.

Correção:

  1. Extraia novamente a chave do site do atributo data-sitekey da página de destino ou do parâmetro k do URL âncora reCAPTCHA.
  2. Certifique-se de que o valor não esteja vazio ou truncado.
{
  "googlekey": ""
}

{
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}

ERROR_BAD_TOKEN_OR_PAGEURL

Causa: A combinação de googlekey (sitekey) e pageurl é inválida. A chave do site não está registrada para o URL da página fornecida.

Causas comuns:

  • O widget reCAPTCHA é carregado dentro de um iframe em um subdomínio diferente. Você está usando o URL da página pai em vez do URL do iframe.
  • A chave do site pertence a uma página ou domínio diferente.
  • A chave do site foi extraída de um ambiente de desenvolvimento/staging.

Correção:

  1. Se o reCAPTCHA estiver em um iframe, use o URL src do iframe como pageurl.
  2. Verifique a chave do site na página de produção ao vivo.
  3. Teste ambos os valores carregando manualmente o URL âncora reCAPTCHA: https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Causa: A imagem enviada excede o tamanho máximo permitido.

Correção: Compacte ou redimensione a imagem antes de enviar. Use JPEG para fotos e PNG para capturas de tela.

ERROR_ZERO_CAPTCHA_FILESIZE

Causa: O arquivo de imagem é muito pequeno (menos de 100 bytes), indicando um upload vazio ou corrompido.

Correção: Verifique se você está enviando dados de imagem reais, não um arquivo vazio ou uma string base64 quebrada.

ERROR_WRONG_FILE_EXTENSION

Causa: O arquivo enviado tem uma extensão incompatível. Suportado: jpg, jpeg, png, gif.

Correção: Converta a imagem para um formato compatível antes de carregá-la.

ERROR_IMAGE_TYPE_NOT_SUPPORTED

Causa: O servidor não consegue determinar o tipo de imagem a partir do conteúdo do arquivo.

Correção: Converta para um formato padrão (PNG ou JPEG) e certifique-se de que o arquivo não esteja corrompido.

ERROR_UPLOAD

Causa: O servidor não conseguiu ler o arquivo enviado ou a carga base64.

Correção:

  1. Para uploads de arquivos: verifique a codificação de dados do formulário multiparte.
  2. Para base64: verifique se a string base64 está completa e codificada corretamente.
  3. Teste com uma imagem em bom estado para descartar corrupção de arquivo.

ERROR_BAD_PROXY

Causa: O proxy fornecido está inacessível ou foi marcado como inválido pelo sistema.

Correção:

  1. Teste o proxy de forma independente – ele consegue se conectar ao site de destino?
  2. Experimente um proxy diferente.
  3. Verifique o formato: login:password@IP:PORT ou IP:PORT para proxies autenticados por IP.

O uso de proxy deve estar habilitado em sua conta. Entre em contato com o suporte CaptchaAI se ainda não tiver feito isso.

ERROR_BAD_PARAMETERS

Causa: Os parâmetros obrigatórios estão ausentes ou possuem tipos de dados incorretos.

Correção: Verifique a documentação da API para o tipo específico de CAPTCHA que você está resolvendo e verifique se todos os parâmetros necessários estão presentes:

Tipo CAPTCHA Parâmetros obrigatórios
reCAPTCHA v2/v3 key, method=userrecaptcha, googlekey, pageurl
Cloudflare Turnstile key, method=turnstile, sitekey, pageurl
Cloudflare Turnstile em staging key, method=turnstile_staging, pageurl, proxy, proxytype
GeeTest v3 key, method=geetest, gt, challenge, pageurl
BLS key, method=bls, body, textinstructions
Normal/image key, method=post, file ou body

IP_BANNED

Causa: Seu IP foi temporariamente banido após repetidas tentativas de autenticação malsucedidas.

Correção: Aguarde aproximadamente 5 minutos e tente novamente com as credenciais corretas. Não continue enviando solicitações com chaves de API erradas.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

Causa: Ocorreu um erro temporário no servidor.

Correção: Aguarde 10 segundos e tente novamente. Use espera exponencial para falhas repetidas:

import time

retry_delay = 10
for attempt in range(5):
    response = submit_captcha()
    if response.get("status") == 1:
        break
    time.sleep(retry_delay)
    retry_delay *= 2  # 10s, 20s, 40s, 80s, 160s

Erros de pesquisa (res.php)

Esses erros ocorrem quando você verifica o status de uma tarefa enviada.

CAPCHA_NOT_READY

Isso não é um erro. Significa que a solução ainda está em andamento.

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

if result.get("request") == "CAPCHA_NOT_READY":
    time.sleep(5)
    continue  # poll again

Guia de tempo: | Tipo CAPTCHA | Primeira enquete depois | Intervalo de pesquisa | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 segundos | 5 segundos | | Cloudflare Turnstile | 15 segundos | 5 segundos | | Cloudflare Turnstile em staging | 20 segundos | 5 segundos | | GeeTest v3 | 15 segundos | 5 segundos | | Normal/image CAPTCHA | 5 segundos | 5 segundos |

ERROR_CAPTCHA_UNSOLVABLE

Causa: CaptchaAI não conseguiu resolver o CAPTCHA após várias tentativas.

Motivos comuns:

  1. O tipo CAPTCHA não é suportado ou os parâmetros estão errados.
  2. O desafio está corrompido ou expirou.
  3. Para soluções baseadas em proxy: o proxy é muito lento ou inacessível.
  4. O site mudou sua implementação de CAPTCHA.

Correção:

  1. Verifique se seus parâmetros (sitekey, pageurl, método) estão corretos.
  2. Reenvie com uma nova solicitação.
  3. Se estiver usando um proxy, tente um diferente.
  4. Se o erro persistir, o site pode ter mudado – extraia novamente o sitekey e o pageurl.

Não tente novamente o mesmo ID de tarefa. Envie uma nova tarefa com novos parâmetros.

ERROR_WRONG_ID_FORMAT

Causa: O ID do captcha deve ser apenas numérico.

Correção: Verifique se você está enviando o ID exato retornado por in.php (apenas dígitos, sem caracteres extras).

ERROR_WRONG_CAPTCHA_ID

Causa: O ID da tarefa não existe ou expirou.

Correção:

  1. Verifique se você está pesquisando com o ID retornado pelo seu envio.
  2. Os IDs de tarefa podem expirar após longos períodos – reenvie se a tarefa for muito antiga.

ERROR_EMPTY_ACTION

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

Correção: Adicione action=get à sua solicitação res.php:

params = {
    "key": api_key,
    "action": "get",  # Required
    "id": captcha_id,
    "json": 1,
}

ERROR_PROXY_CONNECTION_FAILED

Causa: O solucionador não conseguiu se conectar ao site de destino por meio do seu proxy.

Correção:

  1. O proxy pode estar temporariamente inativo – tente um diferente.
  2. O site de destino pode estar bloqueando o IP do proxy.
  3. Verifique se o proxy pode realmente alcançar o site de destino.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

Eles também podem aparecer em res.php – mesma causa e correção dos erros de envio acima.

Modelo de tratamento de erros

Copie este padrão para tratamento robusto de erros em qualquer linguagem:

Pitão

import time
import requests

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

# Errors that should not be retried (fix the request first)
NO_RETRY_ERRORS = {
    "ERROR_WRONG_USER_KEY",
    "ERROR_KEY_DOES_NOT_EXIST",
    "ERROR_PAGEURL",
    "ERROR_WRONG_GOOGLEKEY",
    "ERROR_GOOGLEKEY",
    "ERROR_BAD_TOKEN_OR_PAGEURL",
    "ERROR_BAD_PARAMETERS",
    "ERROR_WRONG_FILE_EXTENSION",
    "ERROR_IMAGE_TYPE_NOT_SUPPORTED",
    "IP_BANNED",
}

# Errors that can be retried
RETRY_ERRORS = {
    "ERROR_ZERO_BALANCE",
    "ERROR_SERVER_ERROR",
    "ERROR_INTERNAL_SERVER_ERROR",
    "ERROR_UPLOAD",
}


def solve_captcha(submit_data, max_retries=3, max_polls=60):
    """Submit and solve a CAPTCHA with full error handling."""

    # Submit with retry logic
    for attempt in range(max_retries):
        resp = requests.post(SUBMIT_URL, data={**submit_data, "json": 1}, timeout=30)
        resp.raise_for_status()
        data = resp.json()

        if data.get("status") == 1:
            captcha_id = data["request"]
            break

        error = data.get("request", "UNKNOWN")

        if error in NO_RETRY_ERRORS:
            raise ValueError(f"Fatal error (fix request): {error}")

        if error in RETRY_ERRORS and attempt < max_retries - 1:
            time.sleep(10 * (2 ** attempt))
            continue

        raise RuntimeError(f"Submit failed: {error}")
    else:
        raise RuntimeError("Submit failed after max retries")

    # Poll for result
    time.sleep(15)

    for _ in range(max_polls):
        resp = requests.get(
            RESULT_URL,
            params={"key": API_KEY, "action": "get", "id": captcha_id, "json": 1},
            timeout=30,
        )
        data = resp.json()

        if data.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if data.get("status") == 1:
            return data["request"]

        error = data.get("request", "UNKNOWN")
        if error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable — resubmit with fresh parameters")

        raise RuntimeError(f"Poll error: {error}")

    raise TimeoutError("Solve timed out")

Node.js

const NO_RETRY_ERRORS = new Set([
  "ERROR_WRONG_USER_KEY",
  "ERROR_KEY_DOES_NOT_EXIST",
  "ERROR_PAGEURL",
  "ERROR_WRONG_GOOGLEKEY",
  "ERROR_BAD_TOKEN_OR_PAGEURL",
  "ERROR_BAD_PARAMETERS",
  "IP_BANNED",
]);

async function solveCaptcha(submitData, maxRetries = 3, maxPolls = 60) {
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

  // Submit with retry
  let captchaId;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch("https://ocr.captchaai.com/in.php", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ ...submitData, json: "1" }),
    });
    const data = await resp.json();

    if (data.status === 1) {
      captchaId = data.request;
      break;
    }

    if (NO_RETRY_ERRORS.has(data.request)) {
      throw new Error(`Fatal error: ${data.request}`);
    }

    if (attempt < maxRetries - 1) {
      await sleep(10_000 * 2 ** attempt);
      continue;
    }

    throw new Error(`Submit failed: ${data.request}`);
  }

  // Poll for result
  await sleep(15_000);

  for (let i = 0; i < maxPolls; i++) {
    const resp = await fetch(
      `https://ocr.captchaai.com/res.php?${new URLSearchParams({
        key: submitData.key,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );
    const data = await resp.json();

    if (data.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }

    if (data.status === 1) return data.request;

    throw new Error(`Poll error: ${data.request}`);
  }

  throw new Error("Solve timed out");
}

Perguntas frequentes

CAPCHA_NOT_READY é um erro?

Não. Isso significa que a solução ainda está em andamento. Aguarde 5 segundos e pesquise novamente. Isso é normal para todos os tipos de CAPTCHA.

O que devo fazer quando obtiver ERROR_CAPTCHA_UNSOLVABLE?

Envie uma nova tarefa com novos parâmetros. Não tente novamente o mesmo ID de tarefa. Se o erro ocorrer repetidamente, verifique se a chave do site e o pageurl estão corretos e se o tipo CAPTCHA é compatível.

Como posso saber se um erro pode ser tentado novamente?

Os erros do parâmetro/format (ERROR_WRONG_USER_KEY, ERROR_BAD_TOKEN_OR_PAGEURL, ERROR_PAGEURL, etc.) não podem ser repetidos - corrija a solicitação primeiro. Erros de servidor (ERROR_SERVER_ERROR, ERROR_INTERNAL_SERVER_ERROR) podem ser repetidos com espera exponencial. ERROR_ZERO_BALANCE pode ser tentado novamente após aguardar a liberação dos threads.

Por que obtenho ERROR_BAD_PROXY para Cloudflare Turnstile em staging?

Cloudflare Turnstile em staging requer um proxy funcional. O proxy deve ser capaz de acessar o site de destino. Teste-o de forma independente e tente um proxy diferente se falhar. Certifique-se também de que o uso de proxy esteja habilitado em sua conta CaptchaAI.

Onde encontro minha chave API?

Faça login emcaptchaai.come vá paracaptchaai.com/api.php. Sua chave API de 32 caracteres é exibida no painel.

Guias relacionados

  • Início rápido do CaptchaAI- faça sua primeira solução funcionar
  • Como resolver reCAPTCHA v2 usando API- tutorial completo do reCAPTCHA v2
  • Como resolver Cloudflare Turnstile em staging usando API— solução Cloudflare necessária para proxy
  • Erros comuns de solução de reCAPTCHA v2— solução de problemas específica do reCAPTCHA
Os comentários estão desativados para este artigo.