Häufige GeeTest v3-Fehler und Korrekturen

Wenn eine GeeTest-v3-Integration sporadisch fehlschlägt, obwohl der Code seit Wochen unverändert läuft, liegt die Ursache fast immer bei einem einzigen Parameter: einem veralteten challenge. GeeTest v3 erzeugt bei jedem Seitenaufruf einen neuen challenge-Wert – wer ihn zwischenspeichert und wiederverwendet, erntet Ablehnungen, die aussehen wie API-Fehler, aber keine sind.

Die GeeTest-v3-Dokumentation von CaptchaAI ist an dieser Stelle unmissverständlich: Für jede Lösungsanfrage brauchen Sie einen frischen challenge. Sobald das CAPTCHA auf der Seite geladen ist, wird der alte Wert ungültig.

Alle übrigen Fehler verteilen sich auf drei Phasen: beim Senden an in.php, beim Abfragen des Ergebnisses über res.php und bei der Validierung auf der Zielseite (die API liefert gültige Werte, die Seite lehnt sie trotzdem ab). Dieser Leitfaden geht jede Fehlerklasse durch – jeweils mit der schnellsten Korrektur.

Schnelldiagnose: zuerst die Fehlerphase bestimmen

Bevor Sie einzelne Fehlercodes durchgehen, grenzen Sie die Phase ein – die antwortende URL zeigt sofort, wo es klemmt:

1. Sendephase (in.php) – Antworten wie ERROR_WRONG_USER_KEY, ERROR_BAD_PARAMETERS oder ERROR_PAGEURL betreffen die Übermittlung. Ursache ist fast immer ein fehlender oder fehlerhafter Parameter.
2. Abfragephase (res.php) – Meldungen wie CAPCHA_NOT_READY oder ERROR_CAPTCHA_UNSOLVABLE betreffen das Abholen des Ergebnisses. Hier ist ein veralteter challenge die häufigste Ursache.
3. Validierungsphase (Zielseite) – Die API liefert gültige Werte, die Seite lehnt sie dennoch ab. Meist stimmt die Feldzuordnung oder der Seitenkontext nicht.

Loggen Sie die Roh-Antworten von in.php und res.php getrennt, dann ist die Zuordnung eindeutig. Die folgenden Abschnitte gehen jede Phase im Detail durch.

Fehler Nr. 1: der veraltete challenge-Wert

Wenn Sie nur eine Sache zuerst prüfen können, dann die Frische des challenge.

GeeTest v3 arbeitet mit zwei zentralen Parametern:

• gt – der öffentliche Website-Schlüssel (statisch, ändert sich nicht)
• challenge – der dynamische Challenge-Schlüssel (ändert sich bei jedem Seitenaufruf)

Warum es bricht

Der challenge-Wert entsteht in dem Moment, in dem das GeeTest-Widget auf der Seite initialisiert wird. Erfassen Sie ihn einmal und verwenden ihn über mehrere Lösungsanfragen hinweg, wird jede Anfrage nach der ersten entweder

• schon beim Senden von der API abgelehnt oder
• ein Ergebnis erzeugen, das die Zielseite verwirft, weil der challenge abgelaufen ist.

So beheben Sie es

Vor jeder Lösungsanfrage untersuchen Sie den Netzwerkverkehr der Seite und suchen den API-Aufruf, der einen frischen challenge zurückgibt. Wiederholen Sie genau diese Anfrage, um einen neuen Wert zu erhalten, und übermitteln Sie ihn sofort an 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

Faustregel: Liegen zwischen dem Abruf des challenge und dem Absenden der Lösungsanfrage mehr als ein paar Sekunden, aktualisieren Sie den Wert.

Beispiel aus der Praxis: Ein auf einem Hetzner-Server laufender Scraping-Worker fragt ein login-geschütztes Portal ab, dessen Anmeldeseite ein GeeTest-v3-Slider absichert. Solange der Worker den challenge unmittelbar vor jeder Anfrage neu abruft, läuft alles stabil. Wird der Wert dagegen einmal beim Start geladen und über Stunden wiederverwendet, häufen sich ERROR_CAPTCHA_UNSOLVABLE-Antworten – nicht wegen eines API-Problems, sondern weil jeder challenge längst abgelaufen ist.

Fehler beim Senden an in.php

Diese Fehler treten auf, wenn Sie die Aufgabe an https://ocr.captchaai.com/in.php übermitteln. Vier davon lassen sich direkt aus der Antwort ablesen:

Zwei weitere Fehler verlangen einen genaueren Blick auf die Parameter.

ERROR_PAGEURL

Ursache: Der Parameter pageurl fehlt in der Anfrage.

Fix: Ergänzen Sie die vollständige URL der Seite, auf der das GeeTest-Widget geladen wird. Beispiel:

pageurl=https://example.com/login

ERROR_BAD_PARAMETERS

Ursache: Ein oder mehrere Pflichtfelder fehlen oder sind fehlerhaft. Für GeeTest sind folgende Parameter erforderlich:

Fix: Stellen Sie sicher, dass gt, challenge und pageurl vorhanden und korrekt formatiert sind.

Fehler beim Abfragen über res.php

Diese Fehler treten auf, wenn Sie das Ergebnis unter https://ocr.captchaai.com/res.php abfragen. Wichtig vorab: CAPCHA_NOT_READY ist kein Fehler, sondern bedeutet, dass die Lösung noch läuft – GeeTest-v3-Lösungen dauern bei CaptchaAI in der Regel weniger als 12 Sekunden bei hoher Erfolgsquote. Warten Sie dann 5 Sekunden und fragen Sie erneut ab; werten Sie die Meldung nie als Misserfolg.

Fehlt der Parameter action oder ist er leer, antwortet die API mit ERROR_EMPTY_ACTION. Übergeben Sie action=get in jeder Abfrage:

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

Wenn die Zielseite trotz gültiger Antwort ablehnt

Das sind die am schwersten zu diagnostizierenden Fälle: Die CaptchaAI-API liefert ein gültiges Ergebnis, die Zielseite verwirft es dennoch.

Bei einer erfolgreichen GeeTest-v3-Lösung gibt die API drei Werte zurück:

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

Diese müssen an die Zielseite übergeben werden als:

Vier Fehlermodi decken praktisch alle diese Fälle ab – jeweils mit charakteristischem Symptom und gezielter Korrektur:

Für datengetriebene Portale gilt in der DACH-Region zusätzlich: IP-Adressen und abgerufene Nutzerdaten fallen unter die DSGVO. Prüfen Sie vor dem Produktivbetrieb Ihres Scraping- oder Automatisierungs-Workflows die Rechtsgrundlage und dokumentieren Sie Ihre Datenflüsse – unabhängig davon, wie zuverlässig die CAPTCHA-Lösung selbst arbeitet.

Python: vollständige GeeTest-v3-Lösung mit frischem challenge

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://example.com/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: vollständige GeeTest-v3-Lösung mit frischem challenge

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://example.com/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
})();

FAQ

Wie oft muss ich einen neuen challenge abrufen?

Vor jeder einzelnen Lösungsanfrage. Ein challenge ist an einen konkreten Seitenaufruf gebunden und verfällt innerhalb weniger Sekunden. Rufen Sie den Wert direkt vor dem Aufruf von in.php ab und übermitteln Sie ihn ohne Verzögerung; zwischengespeicherte oder über mehrere Anfragen wiederverwendete Werte sind die häufigste Fehlerquelle.

Wie erkenne ich, ob der Fehler beim Senden oder beim Abfragen liegt?

An der antwortenden URL. Fehler, die in.php zurückgibt (ERROR_WRONG_USER_KEY, ERROR_BAD_PARAMETERS, ERROR_PAGEURL), betreffen die Übermittlung. Meldungen von res.php (CAPCHA_NOT_READY, ERROR_CAPTCHA_UNSOLVABLE) betreffen die Ergebnisphase. Loggen Sie beide Roh-Antworten getrennt, dann ist die Zuordnung eindeutig.

Kostet ein fehlgeschlagener GeeTest-Versuch einen Thread?

CaptchaAI rechnet pro gleichzeitigem Thread ab, nicht pro Lösung – ein Thread ist so lange belegt, wie eine Anfrage in Bearbeitung ist. Ein sofort abgelehnter Sende-Fehler gibt den Thread umgehend wieder frei; hängende Wiederholungen mit veraltetem challenge binden dagegen unnötig Threads. Die Tarife reichen von BASIC (15 $/Monat, 5 Threads) bis VIP-3 (7.500 $/Monat, 5.000 Threads).

Worin unterscheidet sich GeeTest v3 von reCAPTCHA v2?

GeeTest v3 ist eine Slider-/Puzzle-Abfrage, kein Kontrollkästchen. Es verlangt einen dynamischen challenge, der pro Lösung neu sein muss, und liefert drei Validierungsfelder (challenge, validate, seccode) statt eines einzelnen Tokens. Wie reCAPTCHA v2 dagegen funktioniert, zeigt reCAPTCHA v2 per API lösen.

Ist GeeTest v4 bei CaptchaAI verfügbar?

Dieser Leitfaden behandelt ausschließlich GeeTest v3, das generell verfügbar ist. GeeTest v4 ist bei CaptchaAI noch nicht verfügbar (Status: bald verfügbar); den aktuellen Stand der unterstützten Typen finden Sie in den CaptchaAI API-Dokumenten.

GeeTest-Workflow reparieren – Checkliste

Wenn Ihre GeeTest-Integration streikt, arbeiten Sie diese vier Punkte der Reihe nach ab:

1. challenge prüfen – Ist der Wert frisch? Holen Sie ihn unmittelbar vor jeder Lösung neu.
2. Parameter prüfen – gt, challenge und pageurl müssen vollständig und korrekt sein.
3. Feldzuordnung prüfen – challenge, validate und seccode gehören exakt in die Felder geetest_challenge, geetest_validate und geetest_seccode.
4. Mit manueller Lösung vergleichen – Erfassen Sie über die Browser-DevTools die exakte Anfragestruktur einer erfolgreichen manuellen GeeTest-Lösung.

Starten Sie mit dem CaptchaAI GeeTest-v3-Löser, gleichen Sie Ihre Parameter mit den API-Dokumenten ab und lesen Sie So funktioniert GeeTest v3, wenn Sie den Challenge-Ablauf im Detail verstehen möchten.

Iterationsprotokoll

Visuelles Asset-Briefing

Heldenbild

• Alt-Text: Entwickler bei der Fehlerbehebung von GeeTest-v3-Fehlern – Diagnose von Sende-, Abfrage- und Validierungsfehlern
• Muss zeigen: Debugging-Kontext mit Fehlerphasen und Fehlerpunkten
• Dateiname: geetest-v3-errors-troubleshooting-hero.png

Bild im Artikel 1

• Platzierung: Nach „Fehler beim Abfragen über res.php“
• Typ: Entscheidungsbaum
• Alt-Text: Entscheidungsbaum für GeeTest-v3-Fehler – Sende- vs. Abfrage- vs. Validierungsfehler
• Dateiname: geetest-v3-error-decision-tree.png

Bild im Artikel 2

• Platzierung: Nach „Wenn die Zielseite trotz gültiger Antwort ablehnt“
• Typ: Ursachen-und-Lösungen-Diagramm
• Alt-Text: Diagramm mit häufigen Ursachen für die Ablehnung durch die Zielseite bei GeeTest v3 und deren Lösungen
• Dateiname: geetest-v3-validation-causes-fixes.png

Verwandte Artikel

• GeeTest v3 per API lösen
• GeeTest-Slide-CAPTCHA: Parameter und API-Leitfaden
• Häufige Grid-Image-CAPTCHA-Fehler und Korrekturen