Depurando chamadas de API CAPTCHA com Charles Proxy

A forma mais rápida de descobrir por que a integração com a API da CaptchaAI está devolvendo erro não é adicionar mais print() no código — é observar a requisição HTTP como ela realmente sai da sua máquina. O Charles Proxy fica entre o seu código e a CaptchaAI e mostra cada requisição, resposta e tempo de execução, byte a byte.

Neste guia você vai:

• Configurar o Charles para interceptar o tráfego HTTPS da CaptchaAI
• Resolver ERROR_WRONG_GOOGLEKEY, token rejeitado e timeout
• Conhecer alternativas gratuitas ao Charles

Configuração inicial do Charles Proxy

Passo 1: instale o Charles e habilite a inspeção SSL

Baixe em charlesproxy.com — disponível para Windows, macOS e Linux. A CaptchaAI usa HTTPS, então habilite a inspeção do tráfego criptografado antes de ver qualquer coisa útil:

1. No menu do Charles, abra Proxy → SSL Proxying Settings → Add
2. Em Host, informe ocr.captchaai.com; em Port, informe 443
3. Depois vá em Help → SSL Proxying → Install Charles Root Certificate
4. Confie no certificado no repositório de certificados do seu sistema operacional

Isso só precisa ser feito uma vez por máquina de desenvolvimento.

Passo 2: aponte seu código para o Charles

Por padrão, o Charles escuta em localhost:8888.

Python:

import requests

proxies = {
    "http": "http://localhost:8888",
    "https": "http://localhost:8888",
}

# Disable SSL verification for Charles (development only)
resp = requests.post(
    "https://ocr.captchaai.com/in.php",
    data={"key": "YOUR_API_KEY", "method": "userrecaptcha", "json": "1"},
    proxies=proxies,
    verify=False,
)

Node.js:

const axios = require('axios');
const HttpsProxyAgent = require('https-proxy-agent');

const agent = new HttpsProxyAgent('http://localhost:8888');

const resp = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: { key: 'YOUR_API_KEY', method: 'userrecaptcha', json: 1 },
  httpsAgent: agent,
});

Latência e dados sensíveis: contexto para times no Brasil

Um worker em sa-east-1 (São Paulo) chamando um proxy em outro continente já soma latência antes mesmo da CAPTCHA ser processada — a aba Timing do Charles separa rede de tempo de resolução.

Sessões salvas do Charles guardam chave de API e tokens em texto claro. Trate como dado sensível sob a LGPD e não compartilhe fora da equipe.

Checklist antes de abrir um chamado de suporte

Erros mais comuns e como resolver

Antes de caçar um bug específico, confirme o básico em cada tipo de requisição:

• Envio (POST /in.php): Content-Type correto, todos os parâmetros obrigatórios no corpo, resposta {"status":1,"request":"TASK_ID"} e duração abaixo de 1 s na aba Timing.
• Consulta / polling (GET /res.php): parâmetros key, action=get, id=TASK_ID; resposta CAPCHA_NOT_READY (continue consultando) ou {"status":1,"request":"TOKEN"}; cada consulta seguida do intervalo de espera do seu código.

ERROR_WRONG_GOOGLEKEY

No Charles, observe o corpo da requisição de envio. Localize o campo googlekey:

# What Charles shows:
key=YOUR_API_KEY&method=userrecaptcha&googlekey=&pageurl=https://example.com&json=1
                                      ^^^^^^^^ empty!

Correção: a extração da sitekey falhou antes do envio — revise o código que a captura na página.

Token rejeitado pelo site de destino

Compare o que a CaptchaAI devolveu com o que o seu código está injetando:

• No Charles, encontre a resposta de /res.php com status: 1
• Copie o token completo do campo request
• Localize a requisição seguinte, enviada ao site de destino
• Confirme que o token está no corpo do formulário como g-recaptcha-response

Requisições que nunca terminam (timeout)

Use a visualização Sequence do Charles para acompanhar o tempo:

POST /in.php     → 234ms ✓
GET  /res.php    → 189ms (CAPCHA_NOT_READY)
GET  /res.php    → 201ms (CAPCHA_NOT_READY)
GET  /res.php    → 195ms (CAPCHA_NOT_READY)
... 23 more ...
GET  /res.php    → 188ms (CAPCHA_NOT_READY)  ← never resolves

Se nunca resolver: verifique se a sitekey e a URL da página estão corretas.

Recursos avançados do Charles para depurar CAPTCHA

Além de capturar tráfego, o Charles tem recursos que aceleram a depuração do dia a dia:

• Repetir requisição: clique com o botão direito em qualquer requisição e escolha Repeat para reenviá-la — útil para testar o polling sem rodar o script inteiro.
• Throttle: em Proxy → Throttle Settings, ative um perfil 3G ou EDGE para confirmar que seu código trata bem respostas lentas e timeouts.

Breakpoints

Configure um breakpoint em /in.php para inspecionar e alterar a requisição antes de ela sair:

• Abra Proxy → Breakpoint Settings → Add
• Em Host, informe ocr.captchaai.com; em Path, informe /in.php
• Marque a opção Request
• Seu código passa a pausar antes de enviar, permitindo editar os parâmetros manualmente

Map Local

Substitua respostas reais da API por arquivos locais para testar sem gastar créditos:

1. Abra Tools → Map Local → Add
2. Mapeie https://ocr.captchaai.com/res.php para um arquivo JSON local
3. Crie um mock_response.json:

{"status": 1, "request": "mock_token_for_testing"}

Alternativas ao Charles Proxy

Configuração rápida do mitmproxy

# Install
pip install mitmproxy

# Run
mitmproxy --listen-port 8080

# Configure Python
proxies = {"https": "http://localhost:8080"}

Perguntas frequentes

Posso usar o Charles Proxy em produção?

Não. É uma ferramenta de desenvolvimento local. Em produção, use logging estruturado — veja logs estruturados para operações CAPTCHA.

Rodar as requisições pelo Charles muda o resultado da resolução?

Não. A CaptchaAI não enxerga o Charles como proxy adicional — as requisições passam de forma transparente, sem afetar token nem tempo de resolução.

O Charles Proxy é pago?

Tem teste gratuito completo, mas o uso contínuo exige licença. Sem orçamento, o mitmproxy é gratuito e cobre o mesmo caso de uso.

O Charles funciona com qualquer tipo de CAPTCHA suportado pela CaptchaAI?

Sim, porque a inspeção acontece no nível de HTTP:

• reCAPTCHA v2/v3
• Cloudflare Turnstile
• GeeTest v3
• Demais tipos suportados pela API

Só muda o valor dos parâmetros enviados em /in.php.

Depure e otimize sua integração com a CaptchaAI

Crie sua conta na CaptchaAI e pegue sua chave de API em captchaai.com.

Guias relacionados

• Como estruturar logs para operações com CAPTCHA
• Referência de códigos de erro da CaptchaAI
• Coleção Postman para testar a API da CaptchaAI