Häufige reCAPTCHA v2-Fehler und Korrekturen

Fast jeder reCAPTCHA v2-Fehler lässt sich auf eine einzige Frage zurückführen: In welcher Phase bricht der Ablauf ab? Sobald Sie das eingeordnet haben, ist die Korrektur meist naheliegend. Die üblichen Verdächtigen sind ein falscher googlekey, eine unpassende pageurl, ein nicht ausgeführter Callback oder ein abgelaufenes Token.

Es gibt genau drei Phasen, in denen etwas schiefgehen kann:

• Übermittlung (in.php): Die API nimmt die Aufgabe gar nicht erst an – meist wegen falscher Parameter.
• Abfrage (res.php): Die Übermittlung hat geklappt, aber das Abholen des Ergebnisses hakt oder die Aufgabe ist unlösbar.
• Zielseite: CaptchaAI liefert ein gültiges Token, doch die Seite ignoriert es trotzdem.

Falls Sie reCAPTCHA v2 zum ersten Mal per API lösen, arbeiten Sie zuerst die Schritt-für-Schritt-Anleitung zu reCAPTCHA v2 durch.

Schnelle Diagnose: Symptom zu Ursache

Wenn Sie es eilig haben, starten Sie hier. Diese Tabelle führt Sie vom sichtbaren Symptom direkt zum ersten Prüfpunkt; die Details zu jedem Fehlercode folgen weiter unten.

Die vier häufigsten Fehlerquellen bei reCAPTCHA v2

Bevor Sie einzelne Fehlercodes nachschlagen, prüfen Sie diese vier Punkte – sie erklären rund 80 % aller Ausfälle. Der erste verdient etwas mehr Aufmerksamkeit, weil er am häufigsten übersehen wird.

Falscher oder fehlender googlekey

Der googlekey (Sitekey) stammt aus dem data-sitekey-Attribut des reCAPTCHA-Widgets oder aus dem k-Parameter der Anker-URL. Ist dieser Wert falsch, leer oder von einer anderen Seite übernommen, weist die API die Aufgabe sofort mit ERROR_GOOGLEKEY oder ERROR_WRONG_GOOGLEKEY ab. So finden Sie den korrekten Sitekey:

# Look for data-sitekey in the page HTML
# <div class="g-recaptcha" data-sitekey="6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-"></div>

# Or find it in the anchor URL
# https://www.google.com/recaptcha/api2/anchor?k=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-

Die übrigen drei Fehlerquellen laufen fast immer nach demselben Muster:

• Falsche pageurl: Die pageurl muss exakt die URL sein, unter der das Widget lädt. Steckt es in einem Iframe auf einer anderen Domain, brauchen Sie die Iframe-URL – sonst folgt ERROR_PAGEURL oder ERROR_BAD_TOKEN_OR_PAGEURL.
• Callback wird nicht ausgeführt: Erwartet die Seite eine JavaScript-Callback-Funktion statt des versteckten Feldes g-recaptcha-response, wird das Formular nie abgesendet. Achten Sie auf data-callback oder eine callback-Eigenschaft in grecaptcha.render().
• Token abgelaufen oder mehrfach verwendet: reCAPTCHA-Tokens gelten nur einmalig und verfallen nach rund 2 Minuten. Wird zu lange gewartet oder ein Token erneut genutzt, lehnt die Zielseite es stillschweigend ab.

Fehler beim Übermitteln der Aufgabe (in.php)

Diese Fehler treten auf, wenn Sie die CAPTCHA-Aufgabe an https://ocr.captchaai.com/in.php übermitteln.

Beispiel: Korrekte Anfrage mit Fehlerbehandlung

import requests

def submit_recaptcha_v2(api_key, sitekey, page_url):
    response = requests.get("https://ocr.captchaai.com/in.php", params={
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "json": 1
    })

    data = response.json()

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

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

    if error == "ERROR_WRONG_USER_KEY":
        raise ValueError("API key format is invalid. Must be 32 characters.")
    elif error == "ERROR_ZERO_BALANCE":
        raise RuntimeError("Account balance is zero. Top up at captchaai.com")
    elif error == "ERROR_PAGEURL":
        raise ValueError("pageurl parameter is missing from request")
    elif error in ("ERROR_GOOGLEKEY", "ERROR_WRONG_GOOGLEKEY"):
        raise ValueError(f"Invalid sitekey. Verify the data-sitekey value on the page.")
    elif error == "ERROR_BAD_TOKEN_OR_PAGEURL":
        raise ValueError("Sitekey/pageurl mismatch. Check if widget is in an iframe.")
    else:
        raise RuntimeError(f"API error: {error}")

# Usage
task_id = submit_recaptcha_v2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login")
print(f"Task submitted: {task_id}")

async function submitRecaptchaV2(apiKey, sitekey, pageUrl) {
  const params = new URLSearchParams({
    key: apiKey,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageUrl,
    json: 1,
  });

  const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const data = await res.json();

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

  const error = data.request || "UNKNOWN_ERROR";
  const fixes = {
    ERROR_WRONG_USER_KEY: "API key format is invalid. Must be 32 characters.",
    ERROR_ZERO_BALANCE: "Account balance is zero. Top up at captchaai.com",
    ERROR_PAGEURL: "pageurl parameter is missing from request",
    ERROR_GOOGLEKEY: "Invalid sitekey. Check the data-sitekey attribute.",
    ERROR_BAD_TOKEN_OR_PAGEURL: "Sitekey/pageurl mismatch. Check iframe context.",
  };

  throw new Error(fixes[error] || `API error: ${error}`);
}

// Usage
const taskId = await submitRecaptchaV2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login");
console.log(`Task submitted: ${taskId}`);

Fehler beim Abfragen des Ergebnisses (res.php)

Diese Fehler treten auf, wenn Sie das Ergebnis unter https://ocr.captchaai.com/res.php abfragen.

Beispiel: Abfrage mit sauberer Fehlerbehandlung

import time
import requests

def poll_result(api_key, task_id, timeout=120):
    start = time.time()

    while time.time() - start < timeout:
        time.sleep(5)

        response = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1
        })

        data = response.json()

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

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

        if error == "CAPCHA_NOT_READY":
            continue  # normal — keep waiting
        elif error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable. Submit a new task with fresh params.")
        elif error in ("ERROR_WRONG_ID_FORMAT", "ERROR_WRONG_CAPTCHA_ID"):
            raise ValueError(f"Invalid task ID: {task_id}")
        else:
            raise RuntimeError(f"Polling error: {error}")

    raise TimeoutError(f"Solve timed out after {timeout}s")

# Usage
token = poll_result("YOUR_API_KEY", task_id)
print(f"Token: {token[:50]}...")

async function pollResult(apiKey, taskId, timeout = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    await new Promise((r) => setTimeout(r, 5000));

    const params = new URLSearchParams({
      key: apiKey,
      action: "get",
      id: taskId,
      json: 1,
    });

    const res = await fetch(`https://ocr.captchaai.com/res.php?${params}`);
    const data = await res.json();

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

    if (data.request === "CAPCHA_NOT_READY") continue;
    if (data.request === "ERROR_CAPTCHA_UNSOLVABLE")
      throw new Error("Unsolvable. Submit a new task.");
    throw new Error(`Polling error: ${data.request}`);
  }

  throw new Error(`Solve timed out after ${timeout / 1000}s`);
}

Wenn die Zielseite ein gültiges Token ablehnt

Die API hat ein gültiges Token geliefert, doch die Zielseite weist es weiterhin zurück. Das sind die zähesten Fehler beim Debuggen, weil aus Sicht der API alles glattgelaufen ist. Zwei dieser Ursachen erfordern kein zusätzliches Skript – prüfen Sie sie zuerst, bevor Sie an der Injektion feilen.

Token abgelaufen

Vergehen zwischen dem Erhalt des Tokens und dem Absenden mehr als rund 2 Minuten, verwirft Google es. Besonders träge Pipelines laufen hier auf: Ein Scraping-Worker auf einem Hetzner-Server holt das Token, verarbeitet danach aber noch mehrere Zwischenschritte, und beim Absenden ist das Token längst tot. Genau dieses Muster sehen Teams oft an BLS-Terminportalen, wo zwischen Lösung und Absenden zusätzliche Formularlogik liegt.

Hinweis: Ist Ihre Pipeline langsam, fordern Sie die Lösung erst kurz vor dem Absende-Schritt an – nicht schon am Anfang des Ablaufs. So ist das Token beim Absenden noch frisch.

Widget steckt in einem Iframe

Lädt das reCAPTCHA in einem Iframe von einer anderen Domain, müssen Sie die Quell-URL des Iframes als pageurl verwenden, nicht die URL der übergeordneten Seite. Der Fehler ERROR_BAD_TOKEN_OR_PAGEURL ist der typische Hinweis darauf. Untersuchen Sie die Seite, suchen Sie den Iframe mit dem reCAPTCHA und übergeben Sie dessen src-URL als pageurl.

Token im falschen Feld eingetragen

Manche Seiten erwarten das Token im Textbereich g-recaptcha-response, andere lesen es über grecaptcha.getResponse(), wieder andere über einen Callback. Wählen Sie die falsche Methode, scheitert die Formularübermittlung stillschweigend. Untersuchen Sie die Seite und ermitteln Sie den erwarteten Pfad:

# Method 1: Hidden field injection
driver.execute_script(
    'document.getElementById("g-recaptcha-response").innerHTML = arguments[0];',
    token
)

# Method 2: Callback execution (check data-callback attribute)
driver.execute_script(f'onCaptchaSuccess("{token}");')

# Method 3: Direct form field + submit
driver.execute_script(
    'document.querySelector("[name=g-recaptcha-response]").value = arguments[0];',
    token
)
driver.find_element("css selector", "form").submit()

Callback nicht ausgelöst

Trägt das Widget data-callback="onSuccess" oder nutzt es grecaptcha.render() mit einer callback-Eigenschaft, reicht das Befüllen des versteckten Feldes allein nicht. Sie müssen die Callback-Funktion direkt aufrufen:

// In browser console or Puppeteer/Playwright
// Check for data-callback
const widget = document.querySelector('.g-recaptcha');
const callbackName = widget?.getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

Häufige Fragen

Woran erkenne ich, ob das Widget in einem Iframe liegt?

Zwei schnelle Wege führen zur Antwort:

• Öffnen Sie die Entwicklertools und suchen Sie das Element mit class="g-recaptcha". Ist es in ein <iframe> mit eigener src-Domain eingebettet, ist genau diese Iframe-URL Ihre pageurl.
• Bekommen Sie bei ansonsten korrekten Parametern ERROR_BAD_TOKEN_OR_PAGEURL, ist das ein zuverlässiges Indiz für einen Iframe-Kontext.

Wie lange ist ein reCAPTCHA v2-Token gültig?

Rund 2 Minuten, und nur für eine einzige Verwendung. Planen Sie Ihren Ablauf so, dass zwischen der Lösung durch CaptchaAI und dem Absenden des Formulars möglichst wenig Zeit liegt. Typische Auslöser für scheinbar grundlose Ablehnungen sind:

• zwischengeschaltete Wartezeiten oder sleep-Aufrufe im Ablauf,
• Retries, die das alte Token erneut verwenden,
• langsame Netzwerk- oder Rendering-Schritte vor dem Absenden.

Was unterscheidet ERROR_GOOGLEKEY von ERROR_WRONG_GOOGLEKEY?

Der Unterschied betrifft Inhalt gegen Vorhandensein des Feldes:

• ERROR_GOOGLEKEY – der übergebene Sitekey ist fehlerhaft oder leer. Prüfen Sie den extrahierten Wert.
• ERROR_WRONG_GOOGLEKEY – der Parameter googlekey fehlt in der Anfrage vollständig. Ergänzen Sie ihn.

Braucht reCAPTCHA v2 Enterprise andere Parameter?

Ja. Der hier beschriebene Ablauf gilt für das Standard-reCAPTCHA v2. Enterprise erwartet zusätzliche Angaben und eine eigene Methode. Wenn ERROR_CAPTCHA_UNSOLVABLE trotz korrektem Sitekey wiederholt auftritt, prüfen Sie, ob die Seite tatsächlich Standard-v2 und nicht die Enterprise-Variante einsetzt.

Wie viele Threads brauche ich, um mehrere reCAPTCHA v2 parallel zu lösen?

Ein Thread verarbeitet genau ein CAPTCHA gleichzeitig; Ihre parallele Kapazität ergibt sich also aus der Thread-Zahl Ihres Tarifs – jeweils mit unbegrenzten Lösungen pro Thread:

• BASIC (15 $/Monat): 5 Threads
• STANDARD (30 $/Monat): 15 Threads
• ADVANCE (90 $/Monat): 50 Threads

Für hohes Volumen wählen Sie einfach den Tarif mit genügend gleichzeitigen Threads.

So bringen Sie Ihren reCAPTCHA v2-Workflow zum Laufen

1. Eingaben prüfen – googlekey aus data-sitekey extrahieren und die exakte Seiten-URL verwenden (auf Iframes achten)
2. Injektionsmethode klären – bestimmen, ob die Seite ein verstecktes Feld, einen Callback oder beides erwartet
3. Sofort absenden – das Token innerhalb von 2 Minuten nach Erhalt verwenden
4. Fehlerbehandlung ergänzen – mit den Codebeispielen oben jeden Fehlertyp gezielt abfangen

Starten Sie mit dem CaptchaAI-Solver in Ihr reCAPTCHA v2-Handling. Ihren API-Schlüssel erhalten Sie unter captchaai.com/api.php.

Verwandte Leitfäden

• reCAPTCHA v2 per API lösen – vollständige Schritt-für-Schritt-Anleitung
• reCAPTCHA v2 mit Callback per API lösen – Callback-spezifischer Leitfaden
• Grid Image CAPTCHA automatisch lösen – wie Grid-Abfragen funktionieren
• API-Antwortformate und Fehlercodes – vollständige Fehlercodeliste