Debuggen von CAPTCHA-API-Aufrufen mit Charles Proxy

Wenn CaptchaAI unerwartete Fehlercodes liefert, steckt die Ursache fast immer im Request selbst – in einem fehlenden Parameter, einem falschen Content-Type oder einem leeren googlekey. Charles Proxy macht das sichtbar: Der lokale HTTPS-Proxy zeigt jede Anfrage, Antwort und jedes Timing zwischen Ihrem Code und CaptchaAI im Klartext.

Charles Proxy für CaptchaAI einrichten

Führen Sie die drei Schritte in dieser Reihenfolge aus:

1. Charles Proxy installieren

Laden Sie Charles von charlesproxy.com herunter. Das Tool läuft unter Windows, macOS und Linux.

2. SSL-Proxying aktivieren

CaptchaAI kommuniziert ausschließlich über HTTPS. Damit Charles den verschlüsselten Datenverkehr lesbar macht:

1. Proxy → SSL Proxying Settings → Add
2. Host: ocr.captchaai.com, Port: 443
3. Help → SSL Proxying → Install Charles Root Certificate
4. Vertrauen Sie dem Zertifikat im Zertifikatspeicher Ihres Betriebssystems

Auf verwalteten Windows-Rechnern, in vielen DACH-Unternehmen Standard, braucht dieser letzte Schritt Administratorrechte.

3. Ihren Code auf Charles umleiten

Charles hört standardmäßig auf localhost:8888. Leiten Sie Ihren HTTP-Client über diesen Port um.

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

Das verify=False gilt nur für die lokale Entwicklung mit Charles.

Verbindungsprobleme schnell beheben

Sehen Sie in Charles noch keinen lesbaren Traffic, liegt es meist an einem dieser vier Punkte:

Requests und Antworten in Charles prüfen

Ein CaptchaAI-Ablauf besteht aus zwei API-Aufrufen, die Sie in Charles einzeln sehen: Absenden an /in.php, Ergebnis abfragen über /res.php.

Aufgabe absenden (POST /in.php)

Klicken Sie auf den Request an /in.php und prüfen Sie vier Punkte:

Diese Probleme werden in Charles sofort sichtbar:

Ergebnis abfragen (GET /res.php)

Prüfen Sie dann die Polling-Anfragen:

Häufige CAPTCHA-Integrationsfehler beheben

Drei Fehlerbilder machen den Großteil der Support-Anfragen aus – alle drei lassen sich in Charles eindeutig zuordnen.

Fehler: ERROR_WRONG_GOOGLEKEY

Öffnen Sie den Body des Absende-Requests und suchen Sie das Feld googlekey:

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

Ist es leer, ist die Sitekey-Extraktion vorgelagert fehlgeschlagen – prüfen Sie den Code, der den sitekey ausliest.

Fehler: Requests laufen in ein Timeout

Öffnen Sie die Sequence-Ansicht, um das Timing zu sehen:

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

Wird das Ergebnis nie aufgelöst, sind meist sitekey oder Page-URL falsch – dann hängt die Abfrage endlos in CAPCHA_NOT_READY.

Fehler: Token von der Zielseite abgelehnt

Vergleichen Sie, was CaptchaAI zurückgibt, mit dem, was Sie in das Formular eintragen: Suchen Sie in Charles die /res.php-Antwort mit status: 1, kopieren Sie das vollständige Token aus dem Feld request und prüfen Sie im darauffolgenden Request an die Zielseite, ob es im Formular-Body als g-recaptcha-response steht. Ist das Token abgeschnitten oder im falschen Feld, sehen Sie beide Werte in Charles direkt nebeneinander.

Nützliche Charles-Funktionen fürs CAPTCHA-Debugging

Vier Funktionen sparen beim CAPTCHA-Debugging besonders viel Zeit:

Besonders Map Local lohnt sich: Ordnen Sie https://ocr.captchaai.com/res.php einer lokalen mock_response.json zu und testen Sie Ihren Token-Handling-Code ganz ohne API-Guthaben – etwa für Fehlerpfade in einer GitLab-CI-Pipeline.

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

Alternativen zu Charles Proxy

Charles ist kostenpflichtig – kostenlose oder plattformspezifische Alternativen:

mitmproxy in wenigen Zeilen

# Install
pip install mitmproxy

# Run
mitmproxy --listen-port 8080

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

Häufige Fragen

Brauche ich Charles Proxy oder reicht das Logging in meinem Code?

Für die ad-hoc-Fehlersuche ist Charles überlegen: Sie sehen den echten Wire-Traffic ohne Code-Umbauten. Für den Dauerbetrieb ergänzen Sie ihn durch strukturiertes Logging – Charles ist kein Produktions-Monitoring.

Sieht CaptchaAI, dass ich über Charles route?

Nein. Charles ist ein transparenter lokaler Proxy. Ihre Requests erreichen ocr.captchaai.com unverändert, das Lösen der CAPTCHA-Abfragen bleibt davon unberührt.

Charles zeigt trotz SSL-Proxying nur verschlüsselten Traffic – warum?

Meist fehlt eines von zwei: ocr.captchaai.com steht nicht in den SSL Proxying Settings, oder das Charles-Root-Zertifikat gilt nicht als vertrauenswürdig. Dann bleibt der Body unlesbar.

Ihre CaptchaAI-Integration debuggen und optimieren

Holen Sie sich Ihren API-Schlüssel unter captchaai.com und sehen Sie Ihren ersten Request live in Charles.

Verwandte Leitfäden

• Strukturiertes Logging für CAPTCHA-Abläufe
• CaptchaAI-Fehlercodes im Überblick
• CaptchaAI-API-Traffic mit Fiddler inspizieren