DEV Community: Bassem Shahin

Image CAPTCHA solver in Python: send the right image to an OCR API and get an answer the site accepts

Bassem Shahin — Thu, 15 Oct 2026 13:00:00 +0000

An image CAPTCHA solver in Python comes down to three steps. Capture the exact image the page showed, in the session that loaded the page. Send those bytes to an OCR solving API and poll until it returns the text. Then type that text into the form and POST it in the same session, along with every hidden field the form carries.

The OCR step gets most of the attention, but it's rarely where things break. The usual failure is step one: code downloads the CAPTCHA URL a second time, the server generates a new code for that request, and a correct answer to the old picture gets rejected. Below is all three steps with runnable code, plus a decision on when local OCR like Tesseract is enough.

The setup

You're automating a form you're allowed to automate: an internal tool, a test environment, a portal you have an account on. It shows distorted letters and digits in an <img> and wants them typed into a text box. The goal is plain requests where possible, Playwright where the page needs a browser, and an accepted POST at the end.

First, check it's a text image CAPTCHA

Three different things get called "image CAPTCHAs", and each needs a different API call:

What you see	What it is	What the solver returns
Wavy letters/digits in one picture, a text box below	Text image CAPTCHA (OCR)	The text, e.g. `fadc5`
"Select all images with crosswalks", 3x3 or 4x4 tiles	Grid image challenge	Tile numbers to click, e.g. `1,4,7`
"I'm not a robot" checkbox, or nothing visible at all	reCAPTCHA / Turnstile (token-based)	A token for a hidden field; there's no image to OCR

This article covers the first row. If you're looking at the third, there's no picture to read; you need the site key and a token flow. I wrote up how to tell reCAPTCHA v2, v3 and Enterprise apart for that case.

Is Tesseract enough?

Try it first if the images are clean: one font, no overlapping characters, no strike-through lines, little rotation. Convert to grayscale, threshold to black and white, and run Tesseract in single-line mode with a character whitelist (--psm 7 -c tessedit_char_whitelist=ABCDEFGHJKLMNPQRSTUVWXYZ23456789). Some older or homemade CAPTCHAs are readable that way.

Tesseract is built to read documents, though. Distortion, characters that touch, and background noise are the features CAPTCHA generators add to defeat exactly that kind of OCR, and a whitelist doesn't fix them. Don't guess from one sample. Save 50 images from your target, label them by hand, and measure. If local OCR is right often enough for your retry budget, keep it. If not, send the image to a solving API, which is what the rest of this article does.

Step 1: capture the exact image the page showed

Most text CAPTCHAs work like this: the page HTML contains <img src="/captcha.php?r=0.123">, and each request to that URL generates a new random code, stores it in your server-side session, and returns its picture. The consequences:

Fetch the image exactly once, with the same cookie jar as the page and the form. Fetching it again (to save a copy, to retry a download, or with a fresh requests.get that has no cookies) replaces the code the server expects.
In a browser, don't download it at all. The browser has already fetched it once to render it. Downloading the src again counts as a second fetch. Screenshot the element instead; you get the exact pixels on screen.
If the src is a data:image/...;base64, URI, the image is already in the HTML. Decode it; there's nothing to download.
If it's drawn on a <canvas>, screenshot the canvas element the same way.

I tested the first rule with real solves against a local test form whose CAPTCHA endpoint stores one code per session. I downloaded the image, downloaded it a second time, then submitted the solver's answer for the first copy. All five tries got Incorrect captcha, including the three where the answer matched the first picture exactly (jjsva for an image showing JJSVA).

Step 2: send it to the solver

The API is the 2Captcha-style in.php/res.php pair: POST the image to in.php with method=post (multipart) or method=base64, get a task id back, then poll res.php until the text comes back. The docs say the image must be JPG, PNG or GIF, between 100 bytes and 100 KB. Enforce that on your side. In my tests the live in.php accepted a 50-byte fragment, a 250 KB PNG and a WebP file without complaint, and the problem only showed up when polling: a nonsense answer, or a non-JSON error page instead of a result.

Two optional flags help. Use regsense=1 when the CAPTCHA is case-sensitive: without it, answers came back in lowercase (fadc5 for an image showing FADC5). Use numeric=1 when it's digits only.

Prerequisites: Python 3.9+, pip install requests pillow, and an API key.

import io
import time
import requests
from PIL import Image

API_KEY = "YOUR_API_KEY"
API = "https://ocr.captchaai.com"
MAX_BYTES = 100 * 1024                       # the API takes 100 B to 100 KB
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


class SolveError(Exception):
    pass


def prepare(img: bytes) -> tuple[bytes, str]:
    """Return (bytes, extension) in a format and size the API accepts."""
    if len(img) < 100 or img.lstrip()[:1] == b"<":
        raise SolveError(f"not a captcha image ({len(img)} bytes): did you save an error page?")
    if img[:8] == b"\x89PNG\r\n\x1a\n" and len(img) <= MAX_BYTES:
        return img, "png"
    if img[:3] == b"\xff\xd8\xff" and len(img) <= MAX_BYTES:
        return img, "jpg"
    if img[:4] == b"GIF8" and len(img) <= MAX_BYTES:
        return img, "gif"
    # WebP, BMP, or too big: re-encode as JPEG, lowering quality until it fits
    try:
        im = Image.open(io.BytesIO(img)).convert("RGB")
    except OSError:                          # PIL can't read it: SVG, a truncated file
        raise SolveError("not a readable image; convert it to PNG or JPG first")
    for quality in (90, 75, 60, 45):
        buf = io.BytesIO()
        im.save(buf, "JPEG", quality=quality)
        if len(buf.getvalue()) <= MAX_BYTES:
            return buf.getvalue(), "jpg"
    raise SolveError("image is still over 100 KB after re-encoding; crop it to the captcha")


def _call(method: str, path: str, **kw) -> dict:
    r = requests.request(method, f"{API}/{path}", timeout=30, **kw)
    try:
        return r.json()
    except ValueError:
        raise SolveError(f"non-JSON reply from {path} (HTTP {r.status_code}): {r.text[:80]!r}")


def solve_image(img: bytes, case_sensitive: bool = False, digits_only: bool = False) -> str:
    data, ext = prepare(img)
    fields = {"key": API_KEY, "method": "post", "json": 1}
    if case_sensitive:
        fields["regsense"] = 1
    if digits_only:
        fields["numeric"] = 1
    sub = _call("POST", "in.php", data=fields, files={"file": (f"captcha.{ext}", data)})
    if sub.get("status") != 1:
        raise SolveError(sub.get("request"))
    task_id = sub["request"]

    time.sleep(5)                            # the docs suggest 5 s before the first poll
    deadline, backoff = time.time() + 120, 5
    while time.time() < deadline:
        try:
            res = _call("GET", "res.php", params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1})
        except requests.RequestException:
            res = {"request": "ERROR_SERVER_ERROR"}
        if res.get("status") == 1:
            return res["request"]            # the text in the image, e.g. "fadc5"
        code = res.get("request")
        if code == "CAPCHA_NOT_READY":
            backoff = 5
            time.sleep(5)
        elif code in TRANSIENT:
            time.sleep(backoff)
            backoff = min(backoff * 2, 30)
        else:
            raise SolveError(code or "empty error from res.php; check the image you sent")
    raise SolveError("timed out after 120 s")

Save it as image_solver.py. prepare() exists because of two real-world inputs: WebP images, which the API doesn't take, and element screenshots on high-DPI screens, which can be well over 100 KB as PNG. In my tests, scaled-up PNGs of 150 to 200 KB came out under 50 KB on the first quality step, and the re-encoded JPEG got the same answer as the original image (xl2xl for both).

Step 3: the whole flow with requests

This loads the form, grabs the hidden fields (CSRF tokens live there), fetches the CAPTCHA once, solves it, and submits, all on one requests.Session. Add pip install beautifulsoup4, then fill in the four constants from DevTools.

import base64
from urllib.parse import urljoin
import requests
from bs4 import BeautifulSoup
from image_solver import solve_image, SolveError

PAGE_URL = "https://example.com/signup"     # the page with the form
CAPTCHA_IMG = "img#captcha"                 # CSS selector for the captcha <img>
CAPTCHA_FIELD = "captcha"                   # name of the input the answer goes in
REJECTED = "incorrect captcha"              # text the site shows on a wrong answer
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36"


def load_form(s: requests.Session) -> tuple[str, dict, bytes]:
    soup = BeautifulSoup(s.get(PAGE_URL, timeout=30).text, "html.parser")
    form = soup.find("form")
    action = urljoin(PAGE_URL, form.get("action") or PAGE_URL)
    fields = {i["name"]: i.get("value", "")              # CSRF token and other hidden inputs
              for i in form.select("input[type=hidden][name]")}
    src = urljoin(PAGE_URL, soup.select_one(CAPTCHA_IMG)["src"])
    if src.startswith("data:image"):
        image = base64.b64decode(src.split(",", 1)[1])  # inline image: nothing to download
    else:
        image = s.get(src, headers={"Referer": PAGE_URL}, timeout=30).content  # ONE fetch
    return action, fields, image


def main() -> None:
    s = requests.Session()
    s.headers["User-Agent"] = UA
    for attempt in range(1, 4):
        action, fields, image = load_form(s)
        try:
            answer = solve_image(image)
        except SolveError as e:
            if str(e) == "ERROR_CAPTCHA_UNSOLVABLE":
                continue                                 # new page, new image
            raise
        print(f"attempt {attempt}: {len(image)} byte image -> {answer!r}")
        fields.update({"email": "me@example.com", CAPTCHA_FIELD: answer})
        r = s.post(action, data=fields, timeout=30)
        if REJECTED not in r.text.lower():
            print(f"accepted: HTTP {r.status_code}")
            return
        print("rejected, loading a fresh captcha")
    raise SystemExit("3 rejections in a row: check the troubleshooting table")


if __name__ == "__main__":
    main()

Here's a real run against the local test form from Step 1, solved by the live API:

attempt 1: 8081 byte image -> '9x90x'
rejected, loading a fresh captcha
attempt 2: 9347 byte image -> 'zrf9y'
accepted: HTTP 200

The retry isn't optional. The test images come from Python's captcha library, whose characters overlap heavily, and wrong reads were common on them: in another run all three attempts were rejected and the script stopped. On a wrong answer it reloads the page for a new image. Never resubmit a different answer for the same picture; most sites have already discarded that code.

The same thing in Playwright

When the page needs a browser, screenshot the element and keep everything else in the page:

from playwright.sync_api import sync_playwright
from image_solver import solve_image

with sync_playwright() as p:
    page = p.chromium.launch().new_page()
    for attempt in range(1, 4):
        page.goto("https://example.com/signup")              # fresh page, fresh image
        png = page.locator("img#captcha").screenshot()      # the pixels on screen, no second fetch
        page.fill("input[name=email]", "me@example.com")
        page.fill("input[name=captcha]", solve_image(png))
        page.click("button[type=submit]")
        page.wait_for_load_state()
        if "incorrect captcha" not in page.content().lower():
            print(f"accepted on attempt {attempt}")
            break

Node.js version

Node 18+ ships fetch, FormData and Blob, so there are no dependencies:

const API = "https://ocr.captchaai.com";
const KEY = "YOUR_API_KEY";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const TRANSIENT = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);

function extOf(buf) {
  if (buf[0] === 0x89 && buf[1] === 0x50) return "png";
  if (buf[0] === 0xff && buf[1] === 0xd8) return "jpg";
  if (buf.subarray(0, 4).toString() === "GIF8") return "gif";
  throw new Error("convert the image to PNG, JPG or GIF first");
}

export async function solveImage(buf, { caseSensitive = false, digitsOnly = false } = {}) {
  if (buf.length < 100 || buf.length > 100 * 1024) {
    throw new Error(`image is ${buf.length} bytes; the API takes 100 B to 100 KB`);
  }
  const form = new FormData();
  form.set("key", KEY);
  form.set("method", "post");
  form.set("json", "1");
  if (caseSensitive) form.set("regsense", "1");
  if (digitsOnly) form.set("numeric", "1");
  form.set("file", new Blob([buf]), `captcha.${extOf(buf)}`);

  const sub = await fetch(`${API}/in.php`, { method: "POST", body: form }).then((r) => r.json());
  if (sub.status !== 1) throw new Error(`submit: ${sub.request}`);

  await sleep(5000);
  const deadline = Date.now() + 120000;
  let backoff = 5000;
  while (Date.now() < deadline) {
    const q = new URLSearchParams({ key: KEY, action: "get", id: sub.request, json: "1" });
    const text = await fetch(`${API}/res.php?${q}`).then((r) => r.text())
      .catch(() => JSON.stringify({ request: "ERROR_SERVER_ERROR" }));  // network error: retry
    let res;
    try {
      res = JSON.parse(text);
    } catch {
      throw new Error(`poll: non-JSON reply: ${text.slice(0, 80)}`);
    }
    if (res.status === 1) return res.request;
    if (res.request === "CAPCHA_NOT_READY") {
      backoff = 5000;
      await sleep(5000);
    } else if (TRANSIENT.has(res.request)) {
      await sleep(backoff);
      backoff = Math.min(backoff * 2, 30000);
    } else {
      throw new Error(`poll: ${res.request || "empty error; check the image you sent"}`);
    }
  }
  throw new Error("timed out after 120 s");
}

// Usage with Playwright: screenshot the element instead of downloading it again
// const png = await page.locator("img#captcha").screenshot();
// await page.fill("input[name=captcha]", await solveImage(png));

Why a correct-looking answer still gets rejected

Symptom	Likely cause	Fix
Rejected every time, answer looks right	Image fetched twice, or with a different session	One session; one fetch, or an element screenshot
`403` or "session expired" on submit	Missing CSRF/hidden field, or the cookie jar changed	Post every hidden input from the same `<form>`
Right letters, wrong case	Site is case-sensitive	Pass `case_sensitive=True` (`regsense=1`)
Letters where only digits belong	Digits-only CAPTCHA	Pass `digits_only=True` (`numeric=1`)
`non-JSON reply from res.php`	The server couldn't use the upload: a fragment under 100 bytes, or WebP sent as-is. `in.php` accepted both in my tests	Check the response's `Content-Type` before solving; `prepare()` rejects fragments and converts WebP
A short nonsense answer (`'7de'` for a noisy 250 KB PNG)	Full-page or high-DPI screenshot over the documented 100 KB, which the server didn't reject	Screenshot the element only; `prepare()` re-encodes under 100 KB
`ERROR_CAPTCHA_UNSOLVABLE`	That picture couldn't be read	Load a fresh image and try again

The first two rows are the same kind of failure as a Turnstile token that works in the browser but 403s from requests: the answer is fine, but the session around it changed between issue and use.

FAQ

What's the difference between an image CAPTCHA solver and an OCR library? An OCR library like Tesseract runs on your machine and is tuned for printed documents. A solver API is built for distorted CAPTCHA text, at the cost of a network round trip and a few seconds of polling. Many pipelines try local OCR first and fall back to the API on a rejection.

Can I send base64 instead of a file upload? Yes. Use method=base64 with the image in a body field instead of method=post with file. The size and format limits are the same.

Does this solve "select all images with traffic lights"? Not with this call. That's a grid challenge, which takes the image plus the instruction text and returns tile numbers; it's covered in the Grid Image guide.

I already have 2Captcha image-solving code. What changes? The in.php/res.php shape is the same, so it's mostly the base URL. I covered that swap in migrating solver code off 2Captcha.

I'm Bassem, and I run CaptchaAI, the API behind ocr.captchaai.com in the code above. If you want to run these scripts against your own form, claim a free thread: 1 thread for 30 days, no card. The Normal Captcha guide has the full parameter and error list.

Invisible reCAPTCHA v2: find the sitekey, solve it with invisible=1 and submit the token (Python and Node)

Bassem Shahin — Mon, 12 Oct 2026 13:00:00 +0000

Invisible reCAPTCHA v2 is the version with no "I'm not a robot" box. The page shows only the small "protected by reCAPTCHA" badge, and the check runs when you click submit (or when the site calls grecaptcha.execute()). If it passes, reCAPTCHA puts a token in the form's g-recaptcha-response field and calls the site's callback. To automate a form like that you need three things: the sitekey (the 40-character key that starts with 6L), a solver request with invisible=1 next to the usual method=userrecaptcha, and the right place to put the token. On a plain HTML form that place is a POST field, so you often don't need a browser at all.

This post walks through all three with code you can run against Google's public invisible demo: a Python finder that reads the sitekey and the form from the HTML, a Playwright check for widgets that only exist after JavaScript runs, and a solve-and-submit script in Python and in Node.

How to tell an invisible widget from a checkbox or v3

An invisible v2 widget is declared in one of four ways. The first three are in the HTML; the last is in a script.

Markup	Example
a `div` with `data-size="invisible"`, run by `grecaptcha.execute()`	`<div class="g-recaptcha" data-sitekey="6Lc..." data-size="invisible" data-callback="onSubmit">`
the `g-recaptcha` class on the submit button	`<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">`
a `div` bound to a button by id	`<div class="g-recaptcha" data-sitekey="6Lc..." data-bind="submit-btn" data-callback="onSuccess">`
explicit rendering	`grecaptcha.render("box", { sitekey: "6Lc...", size: "invisible", callback: onToken })`

Google's two public demos use the second and third forms, and neither one ever writes the word "invisible". That's why searching the page for invisible misses half the real widgets.

The thing most often mistaken for invisible v2 is reCAPTCHA v3. It also has no checkbox and shows the same badge. The difference is in the script tag and the call: v3 loads api.js?render=<sitekey> and asks for a token with grecaptcha.execute(sitekey, {action: "login"}). v3 needs version=v3 and an action, not invisible=1. If you're unsure which one you have, this comparison of v2, v3 and Enterprise has a detector for all of them. This post stays with invisible v2.

Step 1: find the sitekey and the form in the HTML

When the widget is in the HTML, you need no browser to find it. This finder uses only the standard library. For each widget it returns the sitekey, whether it's invisible, the callback name, and the form it protects: the URL it submits to, the method, and the fields a browser would send with it (disabled inputs and unchecked boxes left out, as a browser does).

"""find_invisible.py: find reCAPTCHA v2 widgets in a page's HTML and the form each one protects."""
import re
from html.parser import HTMLParser
from urllib.parse import urljoin

RENDER = re.compile(r"grecaptcha\.render\(\s*[^,]+,\s*\{([^}]*)\}", re.S)
OPT = r"""['"]?{0}['"]?\s*:\s*['"]([^'"]+)['"]"""


class WidgetFinder(HTMLParser):
    def __init__(self):
        super().__init__()
        self.forms, self.widgets, self.scripts = [], [], []
        self._form = None
        self._in_script = False

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "form":
            self._form = {"action": a.get("action") or "", "method": (a.get("method") or "get").lower(),
                          "id": a.get("id"), "fields": {}}
            self.forms.append(self._form)
        elif tag in ("input", "textarea", "select") and self._form is not None:
            if a.get("name") and "disabled" not in a and a.get("type") not in ("submit", "button", "image"):
                if a.get("type") in ("checkbox", "radio") and "checked" not in a:
                    return
                self._form["fields"][a["name"]] = a.get("value") or ""
        elif tag == "script":
            self._in_script = True
        if "data-sitekey" in a:
            invisible = (a.get("data-size") == "invisible"   # div + grecaptcha.execute()
                         or tag == "button"                    # <button class="g-recaptcha">
                         or "data-bind" in a)                  # div bound to a button id
            self.widgets.append({"sitekey": a["data-sitekey"], "invisible": invisible,
                                 "callback": a.get("data-callback"), "form": self._form})

    def handle_endtag(self, tag):
        if tag == "form":
            self._form = None
        elif tag == "script":
            self._in_script = False

    def handle_data(self, data):
        if self._in_script:
            self.scripts.append(data)


def find_widgets(html, page_url):
    p = WidgetFinder()
    p.feed(html)
    widgets = p.widgets
    # explicit rendering: grecaptcha.render(el, {sitekey: "...", size: "invisible"})
    for body in RENDER.findall("\n".join(p.scripts)):
        key = re.search(OPT.format("sitekey"), body)
        if key:
            size = re.search(OPT.format("size"), body)
            widgets.append({"sitekey": key.group(1), "callback": None, "form": None,
                            "invisible": bool(size and size.group(1) == "invisible")})
    for w in widgets:
        form = w.pop("form") or (p.forms[0] if len(p.forms) == 1 else None)
        w["submit_url"] = urljoin(page_url, form["action"]) if form else None
        w["method"] = form["method"] if form else None
        w["fields"] = dict(form["fields"]) if form else {}
    return widgets

On the two demos and a checkbox page for comparison:

import requests
from find_invisible import find_widgets

for url in ["https://www.google.com/recaptcha/api2/demo?invisible=true",
            "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php",
            "https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php"]:
    html = requests.get(url, timeout=30).text
    print(find_widgets(html, url))

[{'sitekey': '6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs', 'invisible': True, 'callback': 'onSuccess', 'submit_url': 'https://www.google.com/recaptcha/api2/demo?invisible=true', 'method': 'post', 'fields': {}}]
[{'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'invisible': True, 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php', 'method': 'post', 'fields': {'ex-a': 'foo', 'ex-b': 'bar'}}]
[{'sitekey': '6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9', 'invisible': False, 'callback': None, 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php', 'method': 'post', 'fields': {'ex-a': 'foo', 'ex-b': 'bar'}}]

The Google demo's fields is empty because every input on that form is disabled, so a browser sends only the token. A widget created by grecaptcha.render() has no element to attach it to a form, so the finder falls back to the page's only form when there is just one. With several forms, check by hand.

When the HTML has no sitekey: read the anchor iframe

Single-page apps and bundled sites often create the widget from JavaScript that a regex won't find. Let the page render, then read the widget's anchor iframe. Every rendered key gets one, and its URL carries the sitekey as k= and the widget type as size=:

// anchors.mjs: list every reCAPTCHA widget a page actually rendered. npm i playwright
import { chromium } from "playwright";

const url = process.argv[2];
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: "load" });
await page.waitForSelector('iframe[src*="/anchor"]', { state: "attached", timeout: 15_000 });
await page.waitForTimeout(2_000); // give late widgets a moment

for (const frame of page.frames()) {
  const u = new URL(frame.url());
  if (!u.pathname.endsWith("/anchor")) continue;
  console.log({
    sitekey: u.searchParams.get("k"),
    size: u.searchParams.get("size"), // "invisible" for v2 invisible AND for v3
    enterprise: u.pathname.includes("/enterprise/"),
  });
}
await browser.close();

$ node anchors.mjs "https://www.google.com/recaptcha/api2/demo?invisible=true"
{
  sitekey: '6LfP0CITAAAAAHq9FOgCo7v_fb0-pmmH9VW3ziFs',
  size: 'invisible',
  enterprise: false
}

$ node anchors.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php
{
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  size: 'invisible',
  enterprise: true
}
{
  sitekey: '6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys',
  size: 'invisible',
  enterprise: true
}

The second run shows two traps. First, that demo loads a second key, an Enterprise score key that isn't part of the form, and it reports size: 'invisible' too, because v3 and score keys always do. Pick the key the form's widget uses (the one in the HTML, or the one tied to the submit request), not the first anchor you see.

Second, the form's own key came back with enterprise: true, yet the page loads it through the classic api.js. In an earlier run of the same script the same day, the same key was served from /recaptcha/api2/anchor and reported false. A page that also loads enterprise.js can do that. So use the anchor path as a hint only: decide Enterprise by whether the key is used through enterprise.js and grecaptcha.enterprise, which the comparison post covers. For this demo the answer is a standard invisible v2 key.

Step 2: solve it with invisible=1

The solve is a normal reCAPTCHA v2 task on the 2Captcha-style in.php/res.php API:

Parameter	Value
`method`	`userrecaptcha`
`googlekey`	the sitekey from step 1
`pageurl`	the full URL of the page that shows the widget, not the form's action URL
`invisible`	`1`. The docs mark it as required for invisible widgets: without it the solve can fail
`json`	`1`, so the answers are JSON

You get a task id back, wait about 15 seconds, then poll res.php every 5 seconds until the token arrives. Server errors are retried with a backoff capped at 30 seconds. Account and input errors (ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE, ERROR_PAGEURL) stop at once, because retrying won't fix them.

Step 3: post the token with the form

This script ties the steps together. It loads the page, takes the first invisible widget, solves it and posts the form's fields plus g-recaptcha-response to the form's action, which is what the browser would have done after the callback fired. Prerequisites: Python 3.9+ and pip install requests, with find_invisible.py in the same folder.

# solve_invisible.py: solve an invisible reCAPTCHA v2 and post the form, no browser.
# Needs: pip install requests   (find_invisible.py from above sits next to it)
import os
import re
import sys
import time

import requests

from find_invisible import find_widgets

API = "https://ocr.captchaai.com"  # 2Captcha-style in.php / res.php
API_KEY = os.environ.get("CAPTCHAAI_KEY", "YOUR_API_KEY")
UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
      "(KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36")
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def call(path, **kw):
    """One API call; network errors and non-JSON replies come back as a transient error."""
    try:
        return requests.request(timeout=30, url=f"{API}/{path}", **kw).json()
    except (requests.RequestException, ValueError) as exc:
        return {"status": 0, "request": "ERROR_SERVER_ERROR", "detail": str(exc)}


def solve_invisible(sitekey, pageurl, timeout=180):
    if API_KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set CAPTCHAAI_KEY to your API key first")
    if not re.fullmatch(r"6L[\w-]{38}", sitekey):
        raise SystemExit(f"{sitekey!r} doesn't look like a reCAPTCHA sitekey")
    params = {"key": API_KEY, "method": "userrecaptcha", "googlekey": sitekey,
              "pageurl": pageurl, "invisible": 1, "json": 1}
    for attempt in range(3):
        r = call("in.php", method="POST", data=params)
        if r["status"] == 1:
            break
        if r["request"] not in TRANSIENT:  # ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE,
            raise RuntimeError(f"in.php: {r['request']}")  # ERROR_PAGEURL, ...
        time.sleep(5 * 2 ** attempt)
    else:
        raise RuntimeError("in.php: server errors on 3 tries")

    task_id, started, wait = r["request"], time.time(), 5
    time.sleep(15)  # nothing is ready before ~15 s
    while time.time() - started < timeout:
        r = call("res.php", method="GET", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1})
        if r["status"] == 1:
            return r["request"]
        if r["request"] in TRANSIENT:
            wait = min(wait * 2, 30)  # back off on server trouble
        elif r["request"] == "CAPCHA_NOT_READY":
            wait = 5
        else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID, ...
            raise RuntimeError(f"res.php: {r['request']}")
        time.sleep(wait)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


if __name__ == "__main__":
    page = sys.argv[1] if len(sys.argv) > 1 else \
        "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php"
    if not page.startswith(("http://", "https://")):
        sys.exit("Pass the full URL of the page that shows the widget")
    s = requests.Session()
    s.headers["User-Agent"] = UA
    widgets = [w for w in find_widgets(s.get(page, timeout=30).text, page) if w["invisible"]]
    if not widgets:
        sys.exit("No invisible widget in the HTML: it is a checkbox, or a script renders it (see below).")
    w = widgets[0]
    print("widget:", {k: w[k] for k in ("sitekey", "callback", "submit_url")})

    token = sys.argv[2] if len(sys.argv) > 2 else solve_invisible(w["sitekey"], page)
    print("token:", token[:20] + "...")
    # what the browser would have posted: the form's fields plus the token
    data = {**w["fields"], "g-recaptcha-response": token}
    if w["method"] == "post":
        reply = s.post(w["submit_url"], data=data, timeout=30)
    else:  # a GET form sends its fields in the query string
        reply = s.get(w["submit_url"], params=data, timeout=30)
    print("demo backend:", re.findall(r"'(success|hostname)' => '?([\w.-]+)", reply.text),
          re.findall(r"\d+ => '([a-z-]+)'", reply.text))

The demo backend prints the result of its own siteverify call, so the last line shows Google's verdict. With a solved token:

$ CAPTCHAAI_KEY=... python solve_invisible.py
widget: {'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'}
token: 0cAFcWeA4ZrE7MhWVePD...
demo backend: [('success', 'true'), ('hostname', 'recaptcha-demo.appspot.com')] []

You can test the form half without spending a solve: an optional second argument is used as the token. A fake token shows what a rejection looks like:

$ python solve_invisible.py https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php 03AFcWeA-not-a-real-token
widget: {'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'callback': 'onSubmit', 'submit_url': 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'}
token: 03AFcWeA-not-a-real-...
demo backend: [('success', 'false'), ('hostname', 'NULL')] ['invalid-input-response', 'hostname-mismatch']

On your own target there's no siteverify printout. Use the site's own success signal instead: a redirect, a session cookie, or the absence of its "please complete the captcha" message.

The same flow in Node.js

Node 18+ has fetch built in, so this needs no packages. The finder is a regex version of the Python one: good for triage on server-rendered pages, and the anchor check above covers the rest.

// solve-invisible.mjs: the same flow in Node 18+ (built-in fetch, no packages)
const API = "https://ocr.captchaai.com";
const API_KEY = process.env.CAPTCHAAI_KEY ?? "YOUR_API_KEY";
const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
  "(KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36";
const TRANSIENT = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const attr = (tag, name) => tag.match(new RegExp(`\\s${name}=["']([^"']*)["']`, "i"))?.[1];

async function call(path, init = {}) {
  try {
    const res = await fetch(`${API}/${path}`, { ...init, signal: AbortSignal.timeout(30_000) });
    return await res.json();
  } catch (err) { // network error or non-JSON reply: treat as transient
    return { status: 0, request: "ERROR_SERVER_ERROR", detail: err.message };
  }
}

// Regex triage, like find_invisible.py: invisible widgets declared in the HTML
function findInvisible(html, pageUrl) {
  const out = [];
  for (const m of html.matchAll(/<(\w+)\b[^>]*\bdata-sitekey=[^>]*>/gi)) {
    const tag = m[0];
    const invisible = attr(tag, "data-size") === "invisible" ||
      m[1].toLowerCase() === "button" || /\bdata-bind=/i.test(tag);
    if (!invisible) continue;
    const start = html.lastIndexOf("<form", m.index);
    const formTag = start >= 0 ? html.slice(start, html.indexOf(">", start) + 1) : "";
    const formBody = start >= 0 ? html.slice(start, html.indexOf("</form>", start)) : "";
    const fields = {};
    for (const [input] of formBody.matchAll(/<input\b[^>]*>/gi)) {
      const name = attr(input, "name");
      if (name && !/\bdisabled\b/i.test(input) && !/type=["'](submit|button)/i.test(input))
        fields[name] = attr(input, "value") ?? "";
    }
    out.push({
      sitekey: attr(tag, "data-sitekey"),
      callback: attr(tag, "data-callback") ?? null,
      submitUrl: new URL(attr(formTag, "action") || pageUrl, pageUrl).href,
      method: (attr(formTag, "method") || "get").toUpperCase(),
      fields,
    });
  }
  return out;
}

async function solveInvisible(sitekey, pageurl, timeoutMs = 180_000) {
  if (!API_KEY || API_KEY === "YOUR_API_KEY") throw new Error("Set CAPTCHAAI_KEY first");
  if (!/^6L[\w-]{38}$/.test(sitekey)) throw new Error(`${sitekey} isn't a reCAPTCHA sitekey`);
  const params = new URLSearchParams({ key: API_KEY, method: "userrecaptcha",
    googlekey: sitekey, pageurl, invisible: "1", json: "1" });
  let r;
  for (let attempt = 0; ; attempt++) {
    r = await call("in.php", { method: "POST", body: params });
    if (r.status === 1) break;
    if (!TRANSIENT.has(r.request) || attempt === 2) throw new Error(`in.php: ${r.request}`);
    await sleep(5_000 * 2 ** attempt);
  }
  const id = r.request, started = Date.now();
  let wait = 5_000;
  await sleep(15_000);
  while (Date.now() - started < timeoutMs) {
    r = await call(`res.php?${new URLSearchParams({ key: API_KEY, action: "get", id, json: "1" })}`);
    if (r.status === 1) return r.request;
    if (TRANSIENT.has(r.request)) wait = Math.min(wait * 2, 30_000);
    else if (r.request === "CAPCHA_NOT_READY") wait = 5_000;
    else throw new Error(`res.php: ${r.request}`); // ERROR_CAPTCHA_UNSOLVABLE, ...
    await sleep(wait);
  }
  throw new Error(`task ${id} not solved in ${timeoutMs / 1000}s`);
}

const page = process.argv[2] ?? "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php";
if (!/^https?:\/\//.test(page)) throw new Error("Pass the full URL of the page that shows the widget");
const html = await (await fetch(page, { headers: { "User-Agent": UA } })).text();
const [w] = findInvisible(html, page);
if (!w) throw new Error("No invisible widget in the HTML: a checkbox, or rendered by a script");
console.log("widget:", { sitekey: w.sitekey, callback: w.callback, submitUrl: w.submitUrl });

const token = process.argv[3] ?? await solveInvisible(w.sitekey, page);
const data = new URLSearchParams({ ...w.fields, "g-recaptcha-response": token });
const reply = w.method === "POST"
  ? await fetch(w.submitUrl, { method: "POST", headers: { "User-Agent": UA }, body: data })
  : await fetch(`${w.submitUrl.split("?")[0]}?${data}`, { headers: { "User-Agent": UA } });
const body = await reply.text();
console.log("demo backend:", [...body.matchAll(/'(success|hostname)' => '?([\w.-]+)/g)].map((m) => [m[1], m[2]]),
  [...body.matchAll(/\d+ => '([a-z-]+)'/g)].map((m) => m[1]));

$ node solve-invisible.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php 03AFcWeA-not-a-real-token
widget: {
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  callback: 'onSubmit',
  submitUrl: 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'
}
demo backend: [ [ 'success', 'false' ], [ 'hostname', 'NULL' ] ] [ 'invalid-input-response', 'hostname-mismatch' ]

With CAPTCHAAI_KEY set and no second argument, it solves and posts a real token like the Python script:

$ CAPTCHAAI_KEY=... node solve-invisible.mjs
widget: {
  sitekey: '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-',
  callback: 'onSubmit',
  submitUrl: 'https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php'
}
demo backend: [ [ 'success', 'true' ], [ 'hostname', 'recaptcha-demo.appspot.com' ] ] []

When the token doesn't go in a form field

Posting g-recaptcha-response works when the callback only submits the form, as on both demos. Three other setups are common:

The callback does the work. It enables a button, stores the token in React state or calls an API. In a browser you have to call the callback yourself after you fill the textarea. This post on reCAPTCHA v2 callbacks shows how to find it, even when the bundle is minified, and trigger it from Playwright or Selenium.
The token travels in an XHR. Open DevTools, submit once by hand and look at the request in the Network tab. The token may sit in a JSON body under a name like captcha or recaptchaToken. Send it in that request, with the same headers and cookies.
The site runs execute() on page load. It fetches a token as soon as the page opens and sends it later. Tokens are valid for two minutes and can be verified only once, so solve right before you send the request rather than when you load the page.

Troubleshooting

invalid-input-response with a real token. Most often the token expired or was already used. Next, check that pageurl is the page that shows the widget and that you solved the key the form uses, not the extra key the second anchor run found.
The solve works but the site still says "verify you are human". The token went to the wrong place. Compare your request with the browser's request in the Network tab: field name, endpoint and cookies.
ERROR_PAGEURL or ERROR_WRONG_SITEKEY from in.php. The page URL is missing or not a full URL, or the sitekey is wrong. Copy both from the page again.
ERROR_CAPTCHA_UNSOLVABLE from res.php. Submit once more. If it repeats, check the variant: a v3 key sent as invisible v2 won't produce a token the site accepts.
The finder returns nothing on a page that clearly has the badge. Either the widget is rendered by a script (use the anchor check) or it's v3 (api.js?render=...).

FAQ

What is invisible reCAPTCHA v2?
A reCAPTCHA v2 widget with no checkbox. It runs when the user submits the form or the site calls grecaptcha.execute(). Most visitors never see a challenge, and a suspicious one gets the image puzzle. Like the checkbox, it hands the site a token in g-recaptcha-response to verify server-side.

What's the difference between invisible reCAPTCHA v2 and v3?
Invisible v2 returns a pass/fail token and can still show an image challenge. v3 never shows a challenge. It returns a token the site's backend scores from 0.0 to 1.0, tied to an action name. They need different solver parameters: invisible=1 for v2, version=v3 plus the action for v3.

Is invisible=1 really needed?
Yes. The API docs mark it as required for invisible widgets and say a solve without it can fail. Send invisible=1 whenever the widget is invisible, and leave it out for checkbox widgets.

What does "this site key is not enabled for the invisible captcha" mean?
Google shows that error when a key registered for the checkbox type is rendered with size: "invisible". The site chooses the key type when it registers the key, so treat that key as a checkbox key and leave out invisible=1.

Disclosure: I work on CaptchaAI, whose endpoint the examples use. It solves reCAPTCHA v2 Invisible with the parameters above, and the reCAPTCHA v2 Invisible guide lists them. To run the scripts against your own page, claim a free thread: 1 thread for 30 days, no card.

— Bassem

GeeTest v3: why your slider automation keeps failing the second check

Bassem Shahin — Thu, 08 Oct 2026 13:00:00 +0000

Most people meet GeeTest v3 as "the slider one" — drag the puzzle piece into the gap, done. So the
obvious automation is: find the gap with OpenCV, compute the offset, move the slider that many
pixels. That works exactly once, in a demo, and then fails everywhere real.

The reason is that the gap offset is not what GeeTest is checking. It checks how you got
there, and then it checks again on the server.

The actual flow

GeeTest v3 is a three-step handshake, and the puzzle you see is only step two.

Registration. The site's backend asks GeeTest for a challenge and gets back a gt (a public site key, stable per site) and a challenge (a one-time nonce). The page hands both to the GeeTest JS.
The challenge. The JS renders the slider, and while you drag it, records a trajectory — a time-series of positions, plus timing, acceleration, and a few environment signals. On release, it posts that trajectory to GeeTest's ajax/validate endpoint.
Validation. If GeeTest accepts, it returns three values: geetest_challenge, geetest_validate, geetest_seccode. Those go to the site's own backend, which calls GeeTest server-side to confirm them.

Step 3 is where most automation dies. You can get the slider visually correct and still be rejected,
because the trajectory you produced was not plausible, and the seccode never validates.

Why a pixel-perfect slide still fails

The offset is necessary but nowhere near sufficient. What gets you flagged:

Linear motion. A human accelerates, overshoots slightly, corrects, and settles. A for loop moving 3px per tick produces a straight line with constant velocity — which is the single clearest tell there is.
Zero jitter on the Y axis. Real drags wander vertically by a few pixels. Machine drags don't move on Y at all.
Impossible timing. A 200px drag completed in 40ms, or one that starts the instant the puzzle renders with no reaction delay.
A stale challenge. The nonce is single-use and short-lived. Reusing one across retries — or taking 90 seconds of OpenCV work before submitting — invalidates it.
Environment mismatch. navigator.webdriver, a headless UA, or a TLS fingerprint that disagrees with the browser you claim to be, all feed into the same decision.

There is also a v3 vs v4 trap worth naming: GeeTest v4 is a different product with a different
handshake (captcha_id rather than gt/challenge, and a different validation payload). Guides
and libraries for one do not work against the other, and a lot of confusion online comes from
people mixing them. Check which one you're facing before you write any code —
if you see gt= and challenge= in the network tab, you're on v3.

Detecting which one you're on

import re, requests

html = requests.get(target_url, timeout=20).text

# v3 registers with a gt + challenge pair
v3 = re.search(r'["\']?gt["\']?\s*[:=]\s*["\']([a-f0-9]{32})', html)
# v4 uses captchaId / captcha_id
v4 = re.search(r'captcha[_]?[Ii]d["\']?\s*[:=]\s*["\']([a-f0-9]{32})', html)

print("GeeTest v3" if v3 else "GeeTest v4" if v4 else "neither / dynamically loaded")

If neither matches, the parameters are being fetched by JS at runtime — open the network tab and
look for the request to api.geetest.com/gettype.php or register.php; the gt is in there.

Handling it in automation

Two approaches actually work, and they fail for different reasons.

Drive a real browser and produce a real trajectory. Feasible, and the right call if you're
already running Playwright with a good fingerprint. The work is in the motion model: ease-in/ease-out
velocity, a small overshoot and correction near the target, a few pixels of Y drift, and a human
reaction delay before the drag starts. Budget for tuning — a motion curve that passes today can
start failing after a GeeTest model update, and you find out through a rising failure rate rather
than an error message.

Send the parameters to a solving service and get the three values back. You extract gt and
challenge, submit them, and receive geetest_challenge / geetest_validate / geetest_seccode
to post to the site's backend yourself. This is what we do at CaptchaAI —
the API is 2Captcha-compatible, so if you already have solver code the change is the base URL:

import json, requests, time

API   = "https://ocr.captchaai.com"
KEY   = "YOUR_KEY"

r = requests.get(f"{API}/in.php", params={
    "key": KEY,
    "method": "geetest",
    "gt": gt,                      # public site key, usually static
    "challenge": challenge,        # one-time nonce — grab it fresh, see below
    "pageurl": target_url,
    "json": 1,
}, timeout=30).json()

task = r["request"]

time.sleep(15)                     # geetest takes a while; polling sooner just burns requests
while True:
    res = requests.get(f"{API}/res.php", params={
        "key": KEY, "action": "get", "id": task, "json": 1
    }, timeout=30).json()
    if "seccode" in res:           # solved: challenge / validate / seccode come back top-level
        sol = res
        break
    if res.get("status") == 1:     # the same three values, if your client gets them wrapped
        sol = res["request"]
        sol = json.loads(sol) if isinstance(sol, str) else sol
        break
    if res.get("request") != "CAPCHA_NOT_READY":
        raise RuntimeError(res.get("request"))
    time.sleep(5)

# Note the rename: the API returns short keys, but the SITE expects them prefixed.
payload = {
    "geetest_challenge": sol["challenge"],
    "geetest_validate":  sol["validate"],
    "geetest_seccode":   sol["seccode"],
}

The detail people miss: fetch the challenge immediately before you submit. If your code
registers the challenge, then does other work, then solves, the nonce may already be dead and
you'll get a valid-looking seccode that the site rejects — which reads like a solver problem and
isn't one.

The failure mode to watch

GeeTest doesn't usually tell you why it refused. You get a rejection and a fresh puzzle. So the
signal you actually need is first-attempt success rate over time, not per-request errors. A
slow slide from 95% to 80% over a week is the shape of a model update meeting a motion curve that
used to pass — and if you're only looking at exceptions, you won't see it until it's severe.

Whichever route you take, log the rate. It's the only early warning either approach gives you.

I'm Bassem, founder of CaptchaAI. We solve GeeTest v3, reCAPTCHA v2 and
v3 including Enterprise, Cloudflare Turnstile and Challenge, and image/grid types. We do **not*
solve GeeTest v4, hCaptcha or FunCaptcha — worth saying plainly, because picking a solver on a
capability it doesn't have wastes a week. If Cloudflare is your other wall, I've written up
why cf_clearance keeps expiring
and how to solve Turnstile in Playwright.
To run the GeeTest v3 call above against your own target, start with
one free thread for 30 days, no card needed.*

GeeTest v3 solver in Python: from gt and challenge to a seccode the site accepts

Bassem Shahin — Mon, 05 Oct 2026 13:00:00 +0000

A GeeTest v3 solver in Python takes four HTTP calls, and only the middle two talk to the solver. You get a fresh gt and challenge from the site's register endpoint. You send them to a solving API. You poll until it returns challenge, validate and seccode. Then you POST those three back to the site in the same session that fetched the challenge.

When the solve works but the site still says no, the bug is almost always in the first or last call. Below are all four with runnable code, plus a check to run first: v3 and v4 are not interchangeable.

The setup

You're automating a lookup form you're allowed to automate, and a GeeTest v3 slider sits in front of the submit button. The goal is plain requests, no browser, ending in an accepted form POST.

First, confirm it's GeeTest v3 and not v4

Most GeeTest confusion online comes from mixing guides for the two versions. They take different parameters and hand the site different values. Open DevTools, reload, and compare:

Signal	GeeTest v3	GeeTest v4
Page init	`initGeetest({gt, challenge, ...})`	`initGeetest4({captchaId: ...})`
What identifies it	`gt` (32 hex chars) plus a one-time `challenge`	`captcha_id` only
Network	`api.geetest.com` or `api-na.geetest.com` (`gettype.php`, `get.php`, `ajax.php`)	`gcaptcha4.geetest.com`, `static.geetest.com/v4/gt4.js`
What the site receives	`geetest_challenge`, `geetest_validate`, `geetest_seccode`	`lot_number`, `captcha_output`, `pass_token`, `gen_time`

If you'd rather script it, this loads the page once and classifies it by network traffic (needs pip install playwright and playwright install chromium):

import re
from playwright.sync_api import sync_playwright

def geetest_version(url: str) -> str:
    seen = []
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.on("request", lambda req: seen.append(req.url) if "geetest.com" in req.url else None)
        page.goto(url, wait_until="networkidle")
        browser.close()
    if any("gcaptcha4.geetest.com" in u or "/v4/" in u for u in seen):
        return "GeeTest v4 (captcha_id): this guide does not apply"
    if any(re.search(r"/(gettype|get|ajax)\.php", u) for u in seen):
        return "GeeTest v3 (gt + challenge)"
    return "no GeeTest traffic yet: it may only load when you click submit"

Everything below is v3 only. It's the same habit I recommend for reCAPTCHA: identify the variant before writing solver code, since a request for the wrong variant fails in confusing ways.

Step 1: find the register endpoint

On v3 the challenge is not in the HTML. The site's backend mints it: it calls GeeTest's register.php, signs the result with its private key, and hands the page JSON shaped like this:

{"success": 1, "gt": "f1ab2cd4e5f6a7b8c9d0e1f2a3b4c5d6", "challenge": "6f3b2c...", "new_captcha": true}

To find it, filter DevTools' Network tab by Fetch/XHR, reload, and look for a JSON response containing "challenge". It's usually named /register, /geetest/register or /captcha/init, often with a ?t=<timestamp> cache-buster. GeeTest's own demo uses /pc-geetest/register?t=.... Also check whether the page's initGeetest(...) call sets api_server (e.g. api-na.geetest.com); if so, pass it to the solver.

Two rules decide whether the final POST is accepted:

Fresh. Per the API guide linked at the end, a challenge expires after about 10 minutes and becomes invalid once the widget has loaded it. Fetch it right before you solve, and don't let a browser render the widget with it.
Same session. GeeTest's official v3 server SDK demo stores the register status in the server-side session and reads it back when validating. Register with one cookie jar and submit with another, and a site built like that has no record of your challenge.

A GeeTest v3 solver in Python, end to end

Prerequisites: Python 3.9+, pip install requests, your API key, the page and register URLs, and the form's POST URL (visible in DevTools after one manual solve). The request parameters follow the documented in.php/res.php flow (method=geetest, gt, challenge, pageurl, plus optional api_server and userAgent).

import json
import time
import requests

API_KEY = "YOUR_API_KEY"
API = "https://ocr.captchaai.com"
PAGE_URL = "https://example.com/lookup"                 # page that shows the slider
REGISTER_URL = "https://example.com/geetest/register"   # found in Step 1
SUBMIT_URL = "https://example.com/lookup"               # where the form POSTs
API_SERVER = None        # e.g. "api-na.geetest.com" if initGeetest() sets api_server
UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36"
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


class SolveError(Exception):
    pass


def fresh_pair(s: requests.Session) -> dict:
    r = s.get(REGISTER_URL, params={"t": int(time.time() * 1000)}, timeout=30)
    r.raise_for_status()
    data = r.json()
    if not data.get("success"):
        raise SolveError("register returned success=0 (fallback mode), not a normal challenge")
    return data


def solve(gt: str, challenge: str) -> dict:
    params = {"key": API_KEY, "method": "geetest", "gt": gt, "challenge": challenge,
              "pageurl": PAGE_URL, "userAgent": UA, "json": 1}
    if API_SERVER:
        params["api_server"] = API_SERVER
    sub = requests.get(f"{API}/in.php", params=params, timeout=30).json()
    if sub.get("status") != 1:
        raise SolveError(sub.get("request"))
    task_id = sub["request"]
    print(f"task {task_id} submitted, polling...")

    time.sleep(15)                      # the docs suggest 15-20 s before the first poll
    deadline = time.time() + 120
    while time.time() < deadline:
        try:
            res = requests.get(f"{API}/res.php", timeout=30, params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException:
            time.sleep(10)
            continue
        if "seccode" in res:            # solved: {"challenge", "validate", "seccode"}
            return res
        if res.get("status") == 1:      # same three values wrapped in "request"
            sol = res["request"]
            return json.loads(sol) if isinstance(sol, str) else sol
        code = res.get("request")
        if code in TRANSIENT:
            time.sleep(10)
        elif code == "CAPCHA_NOT_READY":
            time.sleep(5)
        else:
            raise SolveError(code)
    raise SolveError("timed out after 120 s")


def main() -> None:
    s = requests.Session()
    s.headers["User-Agent"] = UA
    s.get(PAGE_URL, timeout=30)         # pick up the cookies a normal visit sets
    for attempt in (1, 2):
        pair = fresh_pair(s)            # fresh challenge, same session
        print(f"register: gt={pair['gt'][:8]}... challenge={pair['challenge'][:8]}...")
        try:
            sol = solve(pair["gt"], pair["challenge"])
        except SolveError as e:
            if str(e) == "ERROR_CAPTCHA_UNSOLVABLE" and attempt == 1:
                continue                # never resubmit an old challenge
            raise
        print(f"solved: seccode={sol['seccode'][:12]}...")
        form = {"q": "example"}         # the form's own fields
        form.update({
            "geetest_challenge": sol["challenge"],   # the RETURNED challenge
            "geetest_validate": sol["validate"],
            "geetest_seccode": sol["seccode"],
        })
        r = s.post(SUBMIT_URL, data=form, timeout=30)
        print(f"POST {SUBMIT_URL} -> {r.status_code}")
        return


if __name__ == "__main__":
    main()

Expected output:

register: gt=f1ab2cd4... challenge=6f3b2c1e...
task 73919012345 submitted, polling...
solved: seccode=2a9c04b7e1f3...
POST https://example.com/lookup -> 200

Two details in that code matter more than they look:

Use the challenge the solver returns, not the one you sent. It can come back changed, and the site checks the three values as a set.
The API returns short keys; the site expects the geetest_ prefix, and some sites rename fields in their own JS. Solve once by hand with DevTools open and copy the exact names.

The same solve step in Node.js

Node 18+ has fetch built in. Keep the register and submit calls on one cookie-keeping client, for the same session reason.

const API = "https://ocr.captchaai.com";
const KEY = "YOUR_API_KEY";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function solveGeetestV3({ gt, challenge, pageurl, userAgent }) {
  const q = new URLSearchParams({ key: KEY, method: "geetest", gt, challenge, pageurl, json: "1" });
  if (userAgent) q.set("userAgent", userAgent);
  const sub = await fetch(`${API}/in.php?${q}`).then((r) => r.json());
  if (sub.status !== 1) throw new Error(`submit: ${sub.request}`);

  await sleep(15000);
  const deadline = Date.now() + 120000;
  while (Date.now() < deadline) {
    const res = await fetch(`${API}/res.php?` + new URLSearchParams({
      key: KEY, action: "get", id: sub.request, json: "1",
    })).then((r) => r.json());
    if (res.seccode) return res; // solved: { challenge, validate, seccode }
    if (res.status === 1) {
      return typeof res.request === "string" ? JSON.parse(res.request) : res.request;
    }
    if (res.request !== "CAPCHA_NOT_READY") throw new Error(`poll: ${res.request}`);
    await sleep(5000);
  }
  throw new Error("timed out after 120 s");
}

Why a correct seccode still gets rejected

Sites behind GeeTest v3 rarely say why they rejected you. Check these in order:

Symptom	Likely cause	Fix
Rejected every time	Register and submit used different sessions	One `requests.Session` for both
Rejected after a slow run	Challenge expired or the widget already loaded it	Register right before solving; never render the widget for it
Rejected despite a fresh pair	Original `challenge` sent instead of the returned one	Send `sol["challenge"]`
Field missing (400/422)	Wrong names or a JS rename	Copy names from a manual solve
`success: 0` from register	The site fell back to offline mode	Log it; retry register later
`ERROR_CAPTCHA_UNSOLVABLE`	The solve failed for this challenge	New register call, then resubmit

The first two rows are the same kind of failure as a Turnstile token that works in the browser but 403s from requests. In both cases the solved values are fine; the context around them changed between issue and use.

FAQ

Does this work for GeeTest v4? No. v4 is a different flow (captcha_id in, four different values out), and none of the code above applies.

Do I need a browser? Not for the solve. If the register endpoint needs a token only the page's JS can produce, call it through Playwright's page.request, which shares the page's cookies, and pass the pair to the same solve().

I already have 2Captcha-style GeeTest v3 code. What changes? The in.php/res.php shape is the same, so it's mostly the base URL. I covered that swap in migrating solver code off 2Captcha.

I'm Bassem, and I run CaptchaAI, the API behind ocr.captchaai.com in the code above. It solves GeeTest v3 and not v4, and I'd rather say so here than have you find out in testing. If you want to run this script against your own target, claim a free thread: 1 thread for 30 days, no card. The GeeTest v3 guide has the full parameter and error list.

reCAPTCHA v2 callback: how to find the callback function and trigger it after injecting a token

Bassem Shahin — Thu, 01 Oct 2026 13:00:00 +0000

Your solver returned a valid reCAPTCHA v2 token. You put it into the hidden g-recaptcha-response textarea, and nothing happens. The submit button stays disabled, or the form posts and the server replies "please complete the captcha". The usual cause is a reCAPTCHA v2 callback: the site doesn't watch the textarea, it waits for reCAPTCHA to call one of its own JavaScript functions with the token. This post shows how to find the callback function (it hides in one of three places) and how to trigger it from Playwright or Selenium after you inject the token.

Why filling g-recaptcha-response does nothing

When a real user passes the widget, reCAPTCHA does two things:

It writes the token into the g-recaptcha-response textarea. Each widget on the page has its own.
If the site registered a callback, it calls that function with the token.

Injecting the token only does step 1. On a plain form that posts the textarea, that's enough. On a callback page, step 2 is where the site's logic lives. Typical callbacks:

submit the form: function onSubmit(token) { document.getElementById("demo-form").submit(); }, the pattern from Google's invisible reCAPTCHA docs
enable a submit button that was disabled until now
send the token to an API with fetch()
store the token in React or Vue component state, so the form posts from state and never reads the textarea

Nothing fires those for you. Invisible reCAPTCHA v2 nearly always works this way: there is no checkbox, so the callback is how the site learns the check has finished.

Two limits apply whatever you do. A token is valid for two minutes and can be verified only once. Solve right before you trigger, and never reuse a token.

How to find the reCAPTCHA callback function

Open DevTools on the page with the widget. There are three places to look, from quickest to most reliable.

1. The data-callback attribute. Declarative widgets name the function in the HTML:

<div class="g-recaptcha" data-sitekey="6Lc..." data-callback="onCaptchaDone"></div>

<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">Log in</button>

The value is the name of a global function, so the call is window.onCaptchaDone(token). Search the Elements panel for data-callback.

2. The callback option of grecaptcha.render(). Sites that load api.js?onload=...&render=explicit create the widget in code:

grecaptcha.render("captcha-box", {
  sitekey: "6Lc...",
  callback: (token) => submitLogin(token),
});

Search all scripts (Ctrl+Shift+F in the Sources panel) for grecaptcha.render. If the callback is an anonymous function inside a bundled module, you can't call it by name. The third method handles that.

3. The ___grecaptcha_cfg.clients object. reCAPTCHA keeps every rendered widget's settings in this global. Each client holds a parameters object with sitekey, size and callback, usually two levels down, under minified names that change between reCAPTCHA releases (for example ___grecaptcha_cfg.clients[0].aa.l.callback). So don't hard-code the path. Walk the object and stop at anything that has a sitekey. The callback you find there is either the function itself or the global name from data-callback, so this works for all three setups, including React wrappers.

Save this as find-callbacks.js:

() => {
  const cfg = window.___grecaptcha_cfg;
  const found = [];
  if (!cfg || !cfg.clients) return found;
  const seen = new Set();
  const walk = (obj, keys, depth) => {
    if (!obj || typeof obj !== "object" || depth > 4 || seen.has(obj)) return;
    if (obj instanceof Node || obj === window) return; // skip DOM nodes
    seen.add(obj);
    if (typeof obj.sitekey === "string") {
      const cb = obj.callback;
      found.push({
        keys, // path from clients to the params object
        sitekey: obj.sitekey,
        // "invisible" means send invisible=1; button-bound widgets store no size
        size: obj.size || (obj.bind ? "invisible" : null),
        callbackType: typeof cb, // "function", "string" or "undefined"
        callbackName: typeof cb === "string" ? cb : (cb && cb.name) || null,
      });
      return;
    }
    for (const [k, v] of Object.entries(obj)) walk(v, [...keys, k], depth + 1);
  };
  for (const [id, client] of Object.entries(cfg.clients)) walk(client, [id], 0);
  return found;
}

You can paste it into the console as (...)() to check a page by hand. A callbackType of "undefined" means that widget has no callback: fill the textarea and submit the form yourself.

reCAPTCHA v3 (api.js?render=KEY) registers a client here too, with an id of 100000 or higher, size: "invisible" and no callback, so it can pass for an invisible v2 widget. If a widget turns up that you didn't expect, check which reCAPTCHA variant you're dealing with first, because v3 needs a different request.

Get the token from the solver

A callback page uses the same solver request as any reCAPTCHA v2 widget: method=userrecaptcha, the sitekey as googlekey, and the pageurl where the widget loaded. Add invisible=1 for invisible widgets. It is required, and a token solved without it can be rejected. This is the 2Captcha-compatible in.php/res.php API, so if you're coming from 2Captcha the parameters are identical (the migration post has the diff).

Prerequisites: Python 3.9+, pip install requests, plus playwright or selenium. Save as solver.py next to the two JS files:

import time
from pathlib import Path

import requests

API_KEY = "YOUR_API_KEY"
FIND_JS = Path("find-callbacks.js").read_text()
TRIGGER_JS = Path("trigger-callback.js").read_text()
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def solve_recaptcha_v2(sitekey, pageurl, invisible=False, timeout=120):
    if not API_KEY or API_KEY == "YOUR_API_KEY":
        raise SystemExit("Set API_KEY to your key first")
    params = {"key": API_KEY, "method": "userrecaptcha",
              "googlekey": sitekey, "pageurl": pageurl, "json": 1}
    if invisible:
        params["invisible"] = 1
    r = requests.get("https://ocr.captchaai.com/in.php", params=params, timeout=30).json()
    if r["status"] != 1:  # e.g. ERROR_WRONG_SITEKEY, ERROR_ZERO_BALANCE
        raise RuntimeError(f"in.php: {r['request']}")
    task_id = r["request"]
    time.sleep(15)
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get("https://ocr.captchaai.com/res.php", timeout=30, params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        if r["status"] == 1:
            return r["request"]
        if r["request"] in TRANSIENT:
            time.sleep(10)
            continue
        if r["request"] != "CAPCHA_NOT_READY":  # e.g. ERROR_CAPTCHA_UNSOLVABLE
            raise RuntimeError(f"res.php: {r['request']}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


def pick_widget(widgets):
    if not widgets:
        raise RuntimeError("no reCAPTCHA widget found on this page")
    return next((w for w in widgets if w["callbackType"] != "undefined"), widgets[0])

Trigger the callback after injecting the token

The trigger does both steps a real solve does, in the same order. Filling the textarea covers callbacks that call form.submit(), since that post carries the textarea. Save as trigger-callback.js:

([token, keys]) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach((t) => { t.value = token; });
  // look the callback up again: functions can't travel back to Python
  const params = keys.reduce((o, k) => (o ? o[k] : undefined), window.___grecaptcha_cfg.clients);
  let cb = params && params.callback;
  if (typeof cb === "string") cb = cb.split(".").reduce((o, k) => (o ? o[k] : undefined), window);
  if (typeof cb !== "function") return "no-callback";
  setTimeout(() => cb(token), 0); // async, so evaluate() returns before any navigation
  return "called";
}

Playwright:

from playwright.sync_api import sync_playwright
from solver import FIND_JS, TRIGGER_JS, pick_widget, solve_recaptcha_v2

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com/login")
    page.wait_for_function("() => Object.keys(window.___grecaptcha_cfg?.clients || {}).length > 0")
    w = pick_widget(page.evaluate(FIND_JS))
    print("widget:", w)
    token = solve_recaptcha_v2(w["sitekey"], page.url, invisible=w["size"] == "invisible")
    outcome = page.evaluate(TRIGGER_JS, [token, w["keys"]])
    print("trigger:", outcome)
    if outcome == "no-callback":
        page.click("form [type=submit]")
    page.wait_for_url("**/dashboard", timeout=15000)  # your success signal
    browser.close()

Selenium uses the same two JS files:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from solver import FIND_JS, TRIGGER_JS, pick_widget, solve_recaptcha_v2

driver = webdriver.Chrome()
driver.get("https://example.com/login")
WebDriverWait(driver, 30).until(lambda d: d.execute_script(
    "return Object.keys(window.___grecaptcha_cfg?.clients || {}).length > 0"))
w = pick_widget(driver.execute_script(f"return ({FIND_JS})();"))
token = solve_recaptcha_v2(w["sitekey"], driver.current_url, invisible=w["size"] == "invisible")
outcome = driver.execute_script(f"return ({TRIGGER_JS})(arguments[0]);", [token, w["keys"]])
print("trigger:", outcome)
if outcome == "no-callback":
    driver.find_element(By.CSS_SELECTOR, "form [type=submit]").click()

Expected output on a callback page:

widget: {'keys': ['0', 'aa', 'l'], 'sitekey': '6Lc...', 'size': 'invisible', 'callbackType': 'function', 'callbackName': 'onSubmit'}
trigger: called

The minified keys will differ from aa and l, which is the point of walking the object.

Troubleshooting

The form posts twice, or the server says the token was already used. The callback submitted the form and you clicked submit as well. Only click when the trigger returns no-callback.
A widget bound to a button reports size: null. reCAPTCHA stores no size for a g-recaptcha class on a button or for data-bind, so the finder treats a set bind as invisible. If a widget you know is invisible still shows null, pass invisible=True yourself.
The submit handler checks grecaptcha.getResponse(). That call reads the widget's g-recaptcha-response textarea, so the fill in the trigger already covers it. There's no need to override it.
The callback ran but the server rejects the token. Check that pageurl is the page that rendered the widget (not the form's action URL), that you solved the right widget's sitekey, that invisible widgets got invisible=1, and that fewer than two minutes passed.
ERROR_CAPTCHA_UNSOLVABLE from res.php. Resubmit once. If it repeats, re-check the sitekey and the variant.

Cloudflare Turnstile has the same trap, since many sites put a data-callback on the cf-turnstile div. The Playwright walkthrough for Turnstile covers that token flow.

FAQ

What is a reCAPTCHA v2 callback? A JavaScript function the site registers, through data-callback or grecaptcha.render(), that reCAPTCHA calls with the token when the check passes. Callback sites submit the form or call their API from inside it.

Do callback pages need a different solver method? No. The token is an ordinary reCAPTCHA v2 token from method=userrecaptcha. Only what you do with it changes. Invisible widgets still need invisible=1.

How do I find the callback when the site's JavaScript is minified? Don't look for a name. Walk ___grecaptcha_cfg.clients to the object that has a sitekey and use its callback property, which holds the function even when it has no usable name.

Disclosure: I work on CaptchaAI, whose endpoint the examples use. It solves reCAPTCHA v2, including invisible and callback widgets, and the reCAPTCHA v2 Callback guide lists the parameters. To run the code above against your own page, claim a free thread: 1 thread for 30 days, no card.

— Bassem

reCAPTCHA v3 solver in Python: find the action, send version=v3, handle Enterprise

Bassem Shahin — Tue, 29 Sep 2026 11:24:28 +0000

When a reCAPTCHA v3 solver in Python returns a token and the site still says no, check the action first. I ran the script below against Google's own v3 demo page while writing this. With the page's real action, the demo's backend accepted the token. With action=login, the token still scored 0.9 and was rejected with action-mismatch.

So a v3 solve comes down to four values: the sitekey, the page URL, version=v3, and the exact action string the page passes to grecaptcha.execute(). Enterprise adds enterprise=1 and gives you back a User-Agent you have to reuse. Below: how to find each one, a solver you can run as-is, and why a valid token still gets turned away.

First, confirm it really is v3

Look at the script tag. api.js?render=SITEKEY means v3. enterprise.js?render=SITEKEY means v3 Enterprise, and the page's calls go through grecaptcha.enterprise.*. A visible checkbox, or a g-recaptcha div with data-size="invisible", means v2. That takes different parameters (invisible=1 for the invisible kind, no action). The full checklist is in reCAPTCHA v2 vs v3 vs Enterprise: how to tell which one you're fighting.

The sitekey is the render= value, with one trap: a page can load more than one. Google's v3 demo loads a second key through enterprise.js, next to the key its execute() call uses. Match the key to the execute() call that fires on your form, not to the first render= you find.

How to find the reCAPTCHA v3 action

The action is a free-form string the site chooses: login, submit, homepage, examples/v3scores. Google returns it to the site's backend next to the score, and a backend can reject any token whose action doesn't match what it expects. That's exactly what happened in my login run. Three ways to find it, quickest first.

1. Search the loaded scripts. In Chrome DevTools, Ctrl+Shift+F (Cmd+Option+F on a Mac) searches every script on the page. Search for execute(. On Google's demo it's in plain sight:

grecaptcha.execute('6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', {action: 'examples/v3scores'})

2. Log it at runtime. Minified bundles can turn the action into a variable, so the search only finds {action: e}. Paste this into the console once the page has loaded, then submit the form:

// Logs the sitekey and action of every execute() call, v3 and Enterprise.
for (const api of [window.grecaptcha, window.grecaptcha?.enterprise]) {
  if (!api || typeof api.execute !== "function") continue;
  const original = api.execute;
  api.execute = function (sitekey, options) {
    console.log("sitekey:", sitekey, "| action:", options?.action);
    return original.apply(this, arguments);
  };
}
// on submit, prints e.g.:  sitekey: 6Lc... | action: submit

3. Set a breakpoint. If the site calls execute() while the page loads, the console hook arrives too late. Open the file from step 1 in the Sources panel (press {} to pretty-print minified code), click the line number of the execute( call, reload, and read action in the Scope pane when it pauses.

Don't skip this when it gets fiddly. The API falls back to verify if action is empty, and verify is rarely what a site checks. Treat it as required.

The reCAPTCHA v3 solver in Python

This talks to a 2Captcha-compatible in.php/res.php API. API_BASE points at the one I run (details at the end); 2Captcha-style services use the same parameter names. It needs pip install requests and an API key in CAPTCHA_API_KEY.

# solve_v3.py: reCAPTCHA v3 / v3 Enterprise solver. Needs: pip install requests
import os
import time

import requests

API_BASE = "https://ocr.captchaai.com"  # a 2Captcha-compatible in.php / res.php API
API_KEY = os.environ.get("CAPTCHA_API_KEY", "YOUR_API_KEY")
RETRYABLE = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def submit(sitekey, pageurl, action, enterprise=False):
    if API_KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set the CAPTCHA_API_KEY environment variable first")
    if not (sitekey and pageurl and action):
        raise ValueError("sitekey, pageurl and action are all required for v3")
    data = {"key": API_KEY, "method": "userrecaptcha", "version": "v3",
            "googlekey": sitekey, "pageurl": pageurl, "action": action, "json": 1}
    if enterprise:
        data["enterprise"] = 1
    for attempt in range(3):
        r = requests.post(f"{API_BASE}/in.php", data=data, timeout=30).json()
        if r["status"] == 1:
            return r["request"]  # the task id
        if r["request"] not in RETRYABLE:  # bad key, zero balance, bad sitekey...
            raise RuntimeError(f"submit rejected: {r['request']}")
        time.sleep(10 * (attempt + 1))
    raise RuntimeError("submit kept failing with server errors")


def solve_v3(sitekey, pageurl, action, enterprise=False, timeout=120):
    task_id = submit(sitekey, pageurl, action, enterprise)
    time.sleep(15)  # the docs advise a 15-20 s wait
    deadline, delay, attempt = time.time() + timeout, 5, 0
    while time.time() < deadline:
        attempt += 1
        try:
            r = requests.get(f"{API_BASE}/res.php", timeout=30, params={
                "key": API_KEY, "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException as exc:  # network blip: back off, keep polling
            print(f"poll {attempt}: {exc}")
            delay = min(delay * 2, 30)
        else:
            if r["status"] == 1:
                # Enterprise answers also carry the solver's User-Agent: keep it
                return r.get("request") or r.get("result"), r.get("user_agent")
            print(f"poll {attempt}: {r['request']}")
            if r["request"] == "CAPCHA_NOT_READY":
                delay = 5
            elif r["request"] in RETRYABLE:
                delay = min(delay * 2, 30)
            else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID, ...
                raise RuntimeError(f"solve failed: {r['request']}")
        time.sleep(delay)
    raise TimeoutError(f"task {task_id} not solved within {timeout}s")

A few details that matter:

Enterprise is the same call plus enterprise=True. Its answer comes back as result and user_agent instead of request (I checked the raw response on 2026-09-28), which is why the return line reads both.
You can't request a score. min_score is not a parameter. The site's backend sets the threshold, and the token clears it or doesn't.
recaptcha.net pages. If the script loads from www.recaptcha.net rather than www.google.com, add "domain": "recaptcha.net" to data.
Polling. CAPCHA_NOT_READY is normal: wait 5 seconds and ask again. Server errors back off up to 30 seconds, and anything else stops the loop, because retrying a bad sitekey only wastes time.

Send the token the way the page does

With v3 the token doesn't ride along in the form automatically, the way v2's g-recaptcha-response field does. The page's own JavaScript puts it wherever it wants: a form field, a JSON key, a query string. So submit the form once by hand with the Network tab open and copy that request exactly. Then be quick about it. Google's docs say a token expires two minutes after it's issued and can be verified only once, so solve right before the request and never reuse a token.

Append this to solve_v3.py. It makes the same request the demo page's JavaScript makes with its token:

if __name__ == "__main__":
    # Google's public v3 demo: a safe target for trying this out
    PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php"
    ACTION = "examples/v3scores"
    token, user_agent = solve_v3(
        sitekey="6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", pageurl=PAGE, action=ACTION)
    print("token:", token[:24] + "...", "| user agent:", user_agent)

    session = requests.Session()
    if user_agent:  # Enterprise tokens are tied to the solver's User-Agent
        session.headers["User-Agent"] = user_agent
    # the same request the demo page's own JavaScript makes with its token
    check = session.get("https://recaptcha-demo.appspot.com/recaptcha-v3-verify.php",
                        params={"action": ACTION, "token": token}, timeout=30)
    print(check.json())

My run on 2026-09-28 (about 17 seconds end to end):

token: 0cAFcWeA7U2MiF6_97mK6g5l... | user agent: None
{'success': True, 'hostname': 'recaptcha-demo.appspot.com', 'challenge_ts': '2026-09-28T11:43:26Z', 'apk_package_name': None, 'score': 0.9, 'action': 'examples/v3scores', 'error-codes': []}

And the run where I solved with action="login" and submitted to the same page:

{'success': False, 'hostname': 'recaptcha-demo.appspot.com', 'challenge_ts': '2026-09-28T11:41:38Z', 'apk_package_name': None, 'score': 0.9, 'action': 'login', 'error-codes': ['action-mismatch']}

Same score, rejected, and action-mismatch is the only error code. The action alone sank it. (That's a demo page, so treat 0.9 as one observation, not a promise. Your target's own threshold decides.)

Why a valid token still gets rejected

Action mismatch. As above. Copy the string exactly, including case and slashes.
Expired or reused. Google reports this as timeout-or-duplicate. One solve per request, submitted inside two minutes.
User-Agent mismatch on Enterprise. Send the user_agent that came back with the token.
Wrong type. v3 parameters won't help against a v2 invisible widget. When in.php can tell the key belongs to another reCAPTCHA type, it answers ERROR_WRONG_KEY_TYPE.
The site's threshold. If the action, timing and User-Agent are right and it still fails, the backend wanted a higher score, or an Enterprise site is applying its own rules on hostname, IP or session. That's a reputation problem, covered in why your reCAPTCHA v3 score is low.

And the errors the API itself returns:

Code	Meaning	Fix
`ERROR_WRONG_USER_KEY`, `ERROR_KEY_DOES_NOT_EXIST`	bad API key	copy it again from the dashboard
`ERROR_ZERO_BALANCE`	not enough balance or threads	top up, or lower concurrency
`ERROR_PAGEURL`, `ERROR_WRONG_SITEKEY`	page URL missing, sitekey malformed	re-extract both from the page
`CAPCHA_NOT_READY`	still solving	poll again in 5 seconds
`ERROR_CAPTCHA_UNSOLVABLE`	the solve failed	check type and parameters, resubmit

FAQ

Can I ask for a 0.9 score? No. There is no min_score parameter. The site decides what score it accepts.

Is v3 Enterprise a different method? No. It's the same method=userrecaptcha and version=v3, plus enterprise=1. Read result and user_agent from the answer.

Do I need a proxy? No, leave it out. Our proxy guide lists reCAPTCHA v3 as not supported with proxies, so send v3 and v3 Enterprise tasks without proxy/proxytype.

I'm Bassem, founder of CaptchaAI, the ocr.captchaai.com endpoint in the script. It solves reCAPTCHA v3 and v3 Enterprise through the 2Captcha-compatible API, so an existing 2Captcha client moves over by changing the base URL. Enterprise sites can still reject a valid token on their own rules, so test against your real target before you build on it. A free thread is enough for that: one thread for 30 days, no card. The full parameter list is in the v3 Enterprise docs.

Build vs buy: what running your own CAPTCHA-solving stack actually costs

Bassem Shahin — Sat, 11 Jul 2026 20:46:18 +0000

Build vs buy: what running your own CAPTCHA-solving stack actually costs

Every team that automates against the public web eventually hits the same fork: a scraper, a monitoring job, a QA suite, or an agent starts tripping CAPTCHAs, and someone asks "should we just build our own solver instead of paying a service?"

It's a fair question. The per-solve prices you see quoted (a dollar or three per 1,000) feel like something you could undercut with a weekend of code. Sometimes you can. But the sticker price of a solving service isn't really what you're comparing against — you're comparing against the fully-loaded cost of owning the problem forever. That second number is the one people underestimate, so let me lay it out honestly, including when building genuinely is the right call.

What "build your own" actually means

The naive version — "I'll just click the checkbox with Playwright" — works in a demo and falls over in production. A real self-hosted solving stack for the modern challenge types (reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile) is not one script. It's a system:

Challenge detection — reliably identifying which captcha is on a page and extracting its sitekey/parameters, across sites that change markup.
Token generation — a fleet of real (or hardened headless) browsers to actually produce valid tokens, because modern challenges are behavior- and signal-based, not image puzzles you can OCR.
Fingerprint + proxy management — reCAPTCHA v3 and Turnstile score the session (IP reputation, TLS/JA3, canvas, behavior), so you need residential/mobile egress and consistent fingerprints or your tokens come back low-score and useless.
Concurrency + queueing — running N solves in parallel without melting your box or getting the whole IP range flagged.
Retry/scoring logic — detecting a failed or low-score solve and retrying intelligently.
Monitoring — success-rate dashboards, alerting when a vendor changes something and your success rate quietly craters overnight.

None of that is exotic. All of it is real engineering, and — this is the part that bites — none of it is done once.

The hidden line item: the maintenance treadmill

Here's the cost that never shows up in the weekend-project estimate. The anti-bot vendors ship changes continuously. Google rotates reCAPTCHA internals; Cloudflare iterates Turnstile; challenge parameters and scoring shift. Every one of those can silently drop your homegrown success rate, and you find out from a downstream failure, not a changelog.

So "build your own" isn't a one-time build cost — it's a standing on-call commitment. Someone on your team now owns keeping a captcha solver alive, and that someone is pulled off your actual product every time the arms race moves.

Rough, honest math for a modest in-house stack:

Line item	Realistic cost
Initial build (detection + browser fleet + proxy glue + retries)	~1–3 engineer-months
Proxies (residential/mobile egress for valid scores)	ongoing $$ — often more than the solver would've cost
Infra (browser fleet, queue, monitoring)	ongoing $
Maintenance (the treadmill — reacting to vendor changes)	~0.2–0.5 of an engineer, indefinitely
Opportunity cost	whatever that engineer isn't building on your core product

At a loaded engineering cost, that maintenance fraction alone is often thousands of dollars a month — before proxies and infra. Compare that to a solving subscription that's typically tens to low-hundreds of dollars a month, and the "cheap" homegrown option frequently isn't.

When building actually wins

I'm not going to pretend buying always wins — it doesn't. Build when:

Solving is your product. If you're a proxy vendor, an anti-detect browser, or a scraping platform, captcha handling is core competency and differentiation. Own it.
You have genuinely unique requirements a general service can't meet — an obscure challenge type, an air-gapped environment, strict data-residency rules.
Extreme volume with margin pressure where, at your scale, an in-house team is demonstrably cheaper than any per-use or per-thread pricing — and you can staff the treadmill.

If one of those is you, building is rational. Budget for the maintenance, not just the build.

When buying wins (most teams)

For everyone else — teams where scraping/automation is a means, not the product — buying is almost always the right call, for one reason: you're offloading the treadmill, not just the code. A solving service absorbs every vendor change so your engineers stay on your roadmap. You wire up an API once and stop thinking about it.

And the integration is genuinely small. Most services expose the same three-step flow — submit the sitekey, poll for the token, inject it — and many are 2Captcha-API-compatible, so if you've ever used one you've basically used all of them:

import requests, time

API_KEY = "YOUR_KEY"
BASE = "https://ocr.captchaai.com" # 2Captcha-compatible endpoint

# 1) submit the challenge (reCAPTCHA v2 shown; Turnstile = method="turnstile" + sitekey)
r = requests.get(f"{BASE}/in.php", params={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY_FROM_THE_PAGE",
    "pageurl": "https://target.example/login",
})
task_id = r.text.split("|")[1]

# 2) poll for the token
while True:
    res = requests.get(f"{BASE}/res.php", params={"key": API_KEY, "action": "get", "id": task_id})
    if res.text == "CAPCHA_NOT_READY":
        time.sleep(5); continue
    token = res.text.split("|")[1]
    break

# 3) inject the token into the page and submit

That's the whole integration surface. No browser fleet, no proxy sourcing for score quality, no 2 a.m. page when a vendor ships a change.

How to actually decide

Skip the per-1,000 sticker comparison. Ask three questions instead:

Is captcha solving part of what we sell? If yes, lean build. If no, lean buy.
Can we staff the maintenance treadmill indefinitely? Not the build — the upkeep. If that makes you wince, buy.
What's the fully-loaded in-house number — build + proxies + infra + that 0.2–0.5 engineer forever + opportunity cost — versus a subscription? Run that comparison, not the sticker one.

For most teams the honest answer is: your engineers are worth more on your product than on an arms race you'll never win outright. Buy the boring part, ship your actual thing.

If you want to sanity-check the buy side against your real volume, CaptchaAI's cost calculator lets you plug in your numbers, and there's a trial if you want to compare success rates against your homegrown prototype before deciding. But whichever way you go, decide on the fully-loaded number — not the weekend-project fantasy.

reCAPTCHA Enterprise vs v3 vs v2: how to tell which one a site uses (enterprise.js, execute, invisible)

Bassem Shahin — Tue, 30 Jun 2026 23:17:04 +0000

Short answer: look at which script the page loads and how it asks for a token. api.js with a visible checkbox is reCAPTCHA v2. api.js with no checkbox, bound to a button or to grecaptcha.execute(), is v2 invisible. api.js?render=<sitekey> plus grecaptcha.execute(sitekey, {action}) is v3. enterprise.js, with calls under grecaptcha.enterprise.*, is reCAPTCHA Enterprise. Enterprise is not a fourth kind of challenge. It is Google Cloud's version of the same checkbox, invisible and score keys, and the site checks its tokens through a different backend API.

Getting this right matters because a token made for the wrong variant often comes back from the solver fine, submits fine, and is then rejected by the site's backend with no useful error. Below you'll find the signals side by side, a small Python detector, a Playwright check for what loads at runtime, and the solver parameters for each variant. I ran all of it against Google's own demo pages on 2026-09-29, and the outputs shown are from those runs.

reCAPTCHA v2 vs v3 vs Enterprise at a glance

	Script	What you see	How the token is made	What the site's backend gets
v2 checkbox	`recaptcha/api.js`	"I'm not a robot" box	user ticks it (image grid if risky)	`success`, `hostname`
v2 invisible	`recaptcha/api.js`	no box, only the badge	a bound button or `grecaptcha.execute()`	`success`, `hostname`
v3	`recaptcha/api.js?render=<sitekey>`	the badge only	`grecaptcha.execute(sitekey, {action})`	`success`, `score`, `action`
Enterprise	`recaptcha/enterprise.js`	any of the three above	`grecaptcha.enterprise.execute()` or `.render()`	`tokenProperties`, `riskAnalysis` (score and reasons)

Two things won't help you tell them apart. The sitekey won't: every variant uses a 40-character key that starts with 6L. The "protected by reCAPTCHA" badge won't either, because v2 invisible and v3 both show it. Some sites load the scripts from www.recaptcha.net instead of www.google.com, and the same rules apply.

reCAPTCHA Enterprise vs v3: what is actually different

This is the pair people mix up most. In the browser, an Enterprise score key behaves exactly like v3: there's no widget, just a badge and an execute() call with an action. The differences are these.

Where the key lives. Enterprise is a Google Cloud product. Its keys belong to a Cloud project, and they come in the same flavours as the classic ones: score, checkbox and invisible.
The client script. The page loads enterprise.js instead of api.js, and every call goes through grecaptcha.enterprise, for example grecaptcha.enterprise.execute(sitekey, {action: 'LOGIN'}). Its requests normally go to /recaptcha/enterprise/... rather than /recaptcha/api2/....
How the backend checks the token. Classic v2 and v3 post the token and a secret to https://www.google.com/recaptcha/api/siteverify. Enterprise creates an assessment through the Cloud API instead. The request looks roughly like this (authentication left out):

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
{"event": {"token": "TOKEN", "siteKey": "6Lc...", "expectedAction": "LOGIN",
           "userAgent": "Mozilla/5.0 ...", "userIpAddress": "203.0.113.7"}}

The answer carries more than a score:

{"tokenProperties": {"valid": true, "action": "LOGIN", "hostname": "example.com"},
 "riskAnalysis": {"score": 0.3, "reasons": ["AUTOMATION"]}}

More signals. reasons can include AUTOMATION, UNEXPECTED_ENVIRONMENT, TOO_MUCH_TRAFFIC or LOW_CONFIDENCE_SCORE. An invalid token also says why in tokenProperties.invalidReason, with values such as EXPIRED, DUPE or MALFORMED. Google documents 11 score levels for Enterprise, but by default a site sees only four: 0.1, 0.3, 0.7 and 0.9.

From the automation side, the browser mechanics are the same as v3 (or v2, for checkbox keys). What changes is how much the backend can compare. The site can pass Google the user agent and IP of the request that carried the token. A token produced in one browser and then submitted with a different user agent can therefore fail. That's why an Enterprise solve comes back with a user_agent you're expected to reuse. It helps to think of Enterprise as v3 with a backend that sees more, not as a harder version of v3.

v2 checkbox vs v2 invisible vs v3: the markup

v2 checkbox is a div with a sitekey, rendered by api.js:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="6Lc..."></div>

Some sites use explicit rendering instead: api.js?onload=onloadCallback&render=explicit plus grecaptcha.render(el, {sitekey: '6Lc...'}). That is still v2. Only render= followed by a sitekey means v3.

v2 invisible has three common markups. Google's own two demos use the two that never say "invisible":

<div class="g-recaptcha" data-sitekey="6Lc..." data-size="invisible" data-callback="onSubmit"></div>

<button class="g-recaptcha" data-sitekey="6Lc..." data-callback="onSubmit">Submit</button>

<div class="g-recaptcha" data-sitekey="6Lc..." data-bind="submit-btn" data-callback="onSuccess"></div>

The programmatic version is grecaptcha.render(el, {sitekey: '6Lc...', size: 'invisible'}).

v3 has no element at all, just the keyed include and an execute() call:

<script src="https://www.google.com/recaptcha/api.js?render=6Lc..."></script>
<script>
  grecaptcha.ready(() =>
    grecaptcha.execute('6Lc...', {action: 'submit'}).then(sendTokenToBackend));
</script>

At runtime, every key in use gets an anchor iframe. The iframe URL carries the sitekey as k= and a size=. A checkbox gets normal or compact. A v2 invisible widget gets invisible, and so does v3. So size=invisible alone doesn't separate v2 invisible from v3. The render=<sitekey> include and an execute() call with an action do.

Detect the reCAPTCHA version from the HTML (Python)

This script reads the page and its same-origin scripts. It reports each sitekey with its type, whether it's Enterprise, and the action or callback if it can find them. It's regex-based, so treat it as a triage tool rather than a parser.

# detect_recaptcha.py: which reCAPTCHA does a page use? Needs: pip install requests
import html
import re
import sys
from urllib.parse import parse_qs, urljoin, urlparse

import requests

KEY = r"6L[\w-]{38}"
SCRIPT = re.compile(r"""<script[^>]+src=["']([^"']*/recaptcha/(?:api|enterprise)\.js[^"']*)["']""", re.I)
TAG = re.compile(r"<(\w+)\s([^>]*data-sitekey[^>]*)>", re.I)
ATTR = re.compile(r"""([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')""")
RENDER = re.compile(r"grecaptcha(\.enterprise)?\.render\([^,]+,\s*\{([^}]*)\}")
EXECUTE = re.compile(rf"""grecaptcha(\.enterprise)?\.execute\(\s*['"]({KEY})['"]\s*,\s*\{{\s*action\s*:\s*['"]([^'"]+)['"]""")


def detect(url):
    ua = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/140.0 Safari/537.36"}
    page = requests.get(url, headers=ua, timeout=30).text
    code = page
    for src in re.findall(r"""<script[^>]+src=["']([^"']+\.js[^"']*)["']""", page)[:20]:
        src = urljoin(url, html.unescape(src))           # actions often live in bundles
        if urlparse(src).netloc == urlparse(url).netloc:
            code += requests.get(src, headers=ua, timeout=30).text

    keys, widget_script = {}, None
    for src in SCRIPT.findall(page):
        src = urljoin(url, html.unescape(src))
        enterprise = "/enterprise.js" in src
        render = parse_qs(urlparse(src).query).get("render", [""])[0]
        if re.fullmatch(KEY, render):                     # render=<sitekey>: score mode
            keys[render] = {"type": "v3", "enterprise": enterprise, "action": None}
        else:                                              # no key: this script renders widgets
            widget_script = "enterprise" if enterprise else "standard"

    for tag, attrs in TAG.findall(page):                   # implicit widgets
        a = {m[0].lower(): m[1] or m[2] for m in ATTR.findall(attrs)}
        invisible = a.get("data-size") == "invisible" or "data-bind" in a or tag.lower() == "button"
        keys[a["data-sitekey"]] = {"type": "v2-invisible" if invisible else "v2-checkbox",
                                   "enterprise": widget_script == "enterprise",
                                   "action": a.get("data-action"),
                                   "callback": a.get("data-callback")}
    for ent, body in RENDER.findall(code):                 # explicit grecaptcha.render(...)
        key = re.search(KEY, body)
        if key:
            invisible = re.search(r"""size['"]?\s*:\s*['"]invisible""", body)
            keys[key.group()] = {"type": "v2-invisible" if invisible else "v2-checkbox",
                                 "enterprise": bool(ent) or widget_script == "enterprise",
                                 "action": None}
    for ent, key, action in EXECUTE.findall(code):          # execute(key, {action})
        info = keys.setdefault(key, {"type": "v3", "enterprise": bool(ent)})
        info.update(type="v3", action=action, enterprise=info["enterprise"] or bool(ent))
    return [{"sitekey": key, **info} for key, info in keys.items()]


if __name__ == "__main__":
    for found in detect(sys.argv[1]):
        print(found)

Here it is against four of Google's demo pages:

$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php
{'sitekey': '6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-', 'type': 'v2-invisible', 'enterprise': False, 'action': None, 'callback': 'onSubmit'}
$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php
{'sitekey': '6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', 'type': 'v3', 'enterprise': False, 'action': 'examples/v3scores'}
$ python detect_recaptcha.py https://www.google.com/recaptcha/api2/demo
{'sitekey': '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-', 'type': 'v2-checkbox', 'enterprise': False, 'action': 'action', 'callback': 'onSuccess'}
$ python detect_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox-explicit.php
{'sitekey': '6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9', 'type': 'v2-checkbox', 'enterprise': False, 'action': None}

On a page with enterprise.js?render=KEY and grecaptcha.enterprise.execute(KEY, {action: 'LOGIN'}) in a bundle, it reports 'type': 'v3', 'enterprise': True, 'action': 'LOGIN'.

It has limits. A minified bundle often passes the action as a variable ({action: e}), which a regex can't read. Scripts added by a tag manager aren't in the HTML at all. The runtime check below covers the second gap, and a DevTools breakpoint on the execute( line covers the first.

Confirm what loads at runtime (Playwright)

This one opens the page in a real browser and records every reCAPTCHA script and anchor iframe it requests.

# sniff_recaptcha.py: what does the page load at runtime?
# Needs: pip install playwright && playwright install chromium
import sys
from urllib.parse import parse_qs, urlparse

from playwright.sync_api import sync_playwright


def sniff(url):
    scripts, anchors = set(), []

    def on_request(req):
        u = urlparse(req.url)
        if "/recaptcha/" not in u.path:
            return
        name = u.path.rsplit("/", 1)[-1]
        if name in ("api.js", "enterprise.js"):
            scripts.add(req.url)
        elif name == "anchor":                            # one anchor iframe per key in use
            q = parse_qs(u.query)
            anchors.append({"sitekey": q.get("k", [""])[0],
                            "enterprise": "/enterprise/" in u.path,
                            "size": q.get("size", [""])[0],   # normal, compact or invisible
                            "sa": q.get("sa", [""])[0]})      # the widget's action, if set

    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        page.on("request", on_request)
        page.goto(url, wait_until="networkidle")
        namespace = page.evaluate("""() => ({
            grecaptcha: typeof window.grecaptcha !== 'undefined',
            enterprise: typeof window.grecaptcha?.enterprise !== 'undefined'})""")
        browser.close()
    return scripts, anchors, namespace


if __name__ == "__main__":
    scripts, anchors, namespace = sniff(sys.argv[1])
    for src in sorted(scripts):
        print("script:", src)
    for anchor in anchors:
        print("anchor:", anchor)
    print("namespace:", namespace)

Here's the output on Google's v3 demo:

$ python sniff_recaptcha.py https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php
script: https://www.google.com/recaptcha/api.js?render=6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9
script: https://www.google.com/recaptcha/enterprise.js?render=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys
anchor: {'sitekey': '6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9', 'enterprise': False, 'size': 'invisible', 'sa': ''}
anchor: {'sitekey': '6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys', 'enterprise': True, 'size': 'invisible', 'sa': ''}
namespace: {'grecaptcha': True, 'enterprise': True}

This output shows the trap. Every page on recaptcha-demo.appspot.com loads a second key through enterprise.js at runtime, and that key isn't in the HTML. The v3 form itself uses 6LdKlZEp... through api.js. If you had gone by "the page loads enterprise.js", you would have solved the wrong key in the wrong mode.

The anchor path doesn't settle it either. The checkbox and invisible demos load both scripts too, and in most of my runs on them the form's own classic widget was served from /recaptcha/enterprise/anchor, on the invisible demo as well. Yet the demo's backend accepted a standard solve for the invisible demo's key, with no enterprise=1 (it's the Python run further down).

So here's the rule that holds up. Start from the sitekey the form actually uses. Then follow that key: which script include carries it, and whether grecaptcha or grecaptcha.enterprise calls execute() or render() with it.

Solver parameters for each reCAPTCHA variant

These are the parameter names of the 2Captcha-style in.php/res.php API, which several solving services share. If you're moving an existing client from one provider to another, the switch is mostly a base-URL change.

Variant	Add to `method=userrecaptcha`, `googlekey`, `pageurl`	Token in the `res.php` answer
v2 checkbox	nothing	`request`
v2 invisible	`invisible=1` (required)	`request`
v2 Enterprise	`enterprise=1`, plus `action=` set to the anchor's `sa=` value if it has one	`result`, plus `user_agent`
v3	`version=v3` and `action=` set to the `execute()` action (both required)	`request`
v3 Enterprise	`version=v3`, `action=...` and `enterprise=1`	`result`, plus `user_agent`

There's no parameter for the score you want, and no min_score. The site's backend sets the threshold. What you control is the action, the timing and the user agent.

One client covers all five. It takes an entry from detect_recaptcha.py:

# solve_recaptcha.py: one client for all five variants. Needs: pip install requests
import os
import re
import time

import requests

API = "https://ocr.captchaai.com"                      # any 2Captcha-style in.php/res.php API
API_KEY = os.environ.get("CAPTCHA_API_KEY", "YOUR_API_KEY")
RETRYABLE = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def build_params(info, pageurl):
    """info is one entry from detect_recaptcha.py: type, enterprise, action."""
    p = {"key": API_KEY, "method": "userrecaptcha", "googlekey": info["sitekey"],
         "pageurl": pageurl, "json": 1}
    if info["type"] == "v2-invisible":
        p["invisible"] = 1                               # required for invisible widgets
    if info["type"] == "v3":
        if not info.get("action"):
            raise ValueError("v3 needs the action passed to execute(); find it first")
        p.update(version="v3", action=info["action"])
    if info["enterprise"]:
        p["enterprise"] = 1
        if info["type"] != "v3" and info.get("action"):
            p["action"] = info["action"]                  # v2 Enterprise: the sa= value
    return p


def solve(params, timeout=180):
    if params["key"] in ("", "YOUR_API_KEY"):
        raise SystemExit("set CAPTCHA_API_KEY first")
    for attempt in range(3):                              # submit, retrying server errors
        r = requests.post(f"{API}/in.php", data=params, timeout=30).json()
        if r["status"] == 1:
            break
        if r["request"] not in RETRYABLE:                 # bad key, bad sitekey, no balance
            raise RuntimeError(f"submit failed: {r['request']}")
        time.sleep(10 * (attempt + 1))
    else:
        raise RuntimeError("submit failed after 3 tries")

    task_id, deadline = r["request"], time.time() + timeout
    time.sleep(15)                                        # nothing is ready before ~15 s
    while time.time() < deadline:
        try:
            r = requests.get(f"{API}/res.php", timeout=30, params={
                "key": params["key"], "action": "get", "id": task_id, "json": 1}).json()
        except requests.RequestException as exc:          # network blip: keep polling
            print("poll error:", exc)
        else:
            if r["status"] == 1:
                # standard answers put the token in "request"; Enterprise answers use
                # "result" and add the solver's "user_agent", which you must reuse
                return r.get("result") or r["request"], r.get("user_agent")
            if r["request"] != "CAPCHA_NOT_READY":        # ERROR_CAPTCHA_UNSOLVABLE, ...
                raise RuntimeError(f"solve failed: {r['request']}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} not solved in {timeout}s")


if __name__ == "__main__":
    # Google's public invisible v2 demo, as detect_recaptcha.py reported it
    PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v2-invisible.php"
    info = {"sitekey": "6LcmDCcUAAAAAL5QmnMvDFnfPTP4iCUYRk2MwC0-",
            "type": "v2-invisible", "enterprise": False, "action": None}
    token, user_agent = solve(build_params(info, PAGE))
    print("token:", token[:20] + "...", "| user_agent:", user_agent)

    # submit it the way the page's form does: POST with g-recaptcha-response
    headers = {"User-Agent": user_agent} if user_agent else {}
    reply = requests.post(PAGE, headers=headers, timeout=30,
                          data={"ex-a": "foo", "ex-b": "bar", "g-recaptcha-response": token})
    print("demo backend:", re.findall(r"'(success|hostname)' => '?([\w.-]+)", reply.text))

$ CAPTCHA_API_KEY=... python solve_recaptcha.py
token: 0cAFcWeA4d2qPybEZsxn... | user_agent: None
demo backend: [('success', 'true'), ('hostname', 'recaptcha-demo.appspot.com')]

The same client in Node 18+ (built-in fetch, no packages), pointed at the v3 demo this time:

// solve_recaptcha.mjs: the same client for Node 18+ (built-in fetch, no packages)
const API = "https://ocr.captchaai.com";
const API_KEY = process.env.CAPTCHA_API_KEY ?? "YOUR_API_KEY";
const RETRYABLE = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const getJson = async (url, init = {}) =>
  (await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) })).json();

function buildParams(info, pageurl) {
  const p = { key: API_KEY, method: "userrecaptcha", googlekey: info.sitekey, pageurl, json: "1" };
  if (info.type === "v2-invisible") p.invisible = "1";
  if (info.type === "v3") {
    if (!info.action) throw new Error("v3 needs the action passed to execute(); find it first");
    Object.assign(p, { version: "v3", action: info.action });
  }
  if (info.enterprise) {
    p.enterprise = "1";
    if (info.type !== "v3" && info.action) p.action = info.action; // v2 Enterprise: sa= value
  }
  return p;
}

async function solve(params, timeoutMs = 180_000) {
  if (!params.key || params.key === "YOUR_API_KEY") throw new Error("set CAPTCHA_API_KEY first");
  let r;
  for (let attempt = 0; ; attempt++) {
    r = await getJson(`${API}/in.php`, { method: "POST", body: new URLSearchParams(params) });
    if (r.status === 1) break;
    if (!RETRYABLE.has(r.request) || attempt === 2) throw new Error(`submit failed: ${r.request}`);
    await sleep(10_000 * (attempt + 1));
  }
  const id = r.request;
  const deadline = Date.now() + timeoutMs;
  await sleep(15_000);
  while (Date.now() < deadline) {
    const q = new URLSearchParams({ key: params.key, action: "get", id, json: "1" });
    try {
      r = await getJson(`${API}/res.php?${q}`);
    } catch (err) {
      console.log("poll error:", err.message); // network blip: keep polling
      await sleep(5_000);
      continue;
    }
    // Enterprise answers carry the token in "result" plus the solver's "user_agent"
    if (r.status === 1) return { token: r.result ?? r.request, userAgent: r.user_agent ?? null };
    if (r.request !== "CAPCHA_NOT_READY") throw new Error(`solve failed: ${r.request}`);
    await sleep(5_000);
  }
  throw new Error(`task ${id} not solved in ${timeoutMs / 1000}s`);
}

// Google's public v3 demo, as detect_recaptcha.py reported it
const PAGE = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php";
const info = { sitekey: "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", type: "v3",
               enterprise: false, action: "examples/v3scores" };
const { token, userAgent } = await solve(buildParams(info, PAGE));
console.log("token:", token.slice(0, 20) + "...", "| userAgent:", userAgent);

// the same check the demo page's own JavaScript runs with its token
const q = new URLSearchParams({ action: info.action, token });
console.log(await getJson(`https://recaptcha-demo.appspot.com/recaptcha-v3-verify.php?${q}`));

$ CAPTCHA_API_KEY=... node solve_recaptcha.mjs
token: 0cAFcWeA6F-w3KX697Jj... | userAgent: null
{
  success: true,
  hostname: 'recaptcha-demo.appspot.com',
  challenge_ts: '2026-09-29T07:53:00Z',
  apk_package_name: null,
  score: 0.9,
  action: 'examples/v3scores',
  'error-codes': []
}

That's one run on a demo page, so don't read the 0.9 as a promise for your own target.

Where the token goes depends on the variant:

v2: it goes into the g-recaptcha-response textarea. If the widget has a data-callback, call that function with the token as well, because on callback-driven forms filling the textarea alone does nothing.
v3 and Enterprise: it goes into whatever field the page's own request uses. Watch the Network tab. It might be g-recaptcha-response in a form post, or a JSON field in an XHR.
Enterprise: also send the request with the user_agent from the answer as your User-Agent header.

Why a correctly solved token still gets rejected

Expired or reused. A token is valid for two minutes and can be verified only once. Classic siteverify reports this as timeout-or-duplicate, and Enterprise reports EXPIRED or DUPE. Solve once per request and submit right away.
Action mismatch. The backend compares the token's action with the one it expects. Google's PHP library, which the demos use, reports this as action-mismatch. Copy the string exactly, including case and slashes.
Wrong variant. This covers v3 parameters sent for a v2 invisible key, a missing invisible=1, and a missing enterprise=1. When the API can tell that the key belongs to another type, in.php answers ERROR_WRONG_KEY_TYPE. Often nothing tells you.
User agent mismatch on Enterprise. Reuse the user_agent that came back with the token.
Wrong page URL. Send the URL of the page where the widget loads. If the widget sits inside an iframe, send the iframe's URL. The hostname in the check has to be the site's.
Score below the site's threshold. If everything above is right and it still fails, you have a reputation problem (IP, browser, behaviour). That's covered in why your reCAPTCHA v3 score is low.
Enterprise site rules. An Enterprise site can reject a valid token on its own rules, based on reasons, IP or session. Test against your real target, not only a demo.

FAQ

Is reCAPTCHA Enterprise the same as v3?
No. Enterprise is the Google Cloud product. Its score keys work like v3 in the browser, but they load enterprise.js, call grecaptcha.enterprise.execute(), and are checked through the assessment API, which returns reasons and token details along with the score. Enterprise also has checkbox and invisible keys that behave like v2.

How do I know if a site uses reCAPTCHA Enterprise?
Find the sitekey the form uses. Then check whether enterprise.js loads that key, or whether it's passed to grecaptcha.enterprise.*. An enterprise.js somewhere on the page isn't enough on its own, because it can belong to another key.

Does render=explicit mean v3?
No. render=explicit is v2's explicit rendering mode. v3 is render= followed by the sitekey.

Can I tell the version from the sitekey?
No. All variants use 40-character keys that start with 6L.

Can I ask the solver for a 0.9 score?
No. There's no min_score parameter. The site decides which score it accepts.

I'm Bassem, and I run CaptchaAI. ocr.captchaai.com in the scripts above is our endpoint, and it solves all five variants in the table through the 2Captcha-compatible API. To try the detector's output against your own target, a free thread is enough: one thread for 30 days, no card. The v3 Enterprise guide lists every parameter.

Cloudflare Turnstile token rejected (403 / timeout-or-duplicate) from Python requests: causes and fix

Bassem Shahin — Sun, 28 Jun 2026 09:54:14 +0000

A Cloudflare Turnstile token that passes in the browser and then gets a 403 or timeout-or-duplicate from Python requests is rarely a bad token. It is a good token used the wrong way: a second time, after its 300-second lifetime, for a different sitekey or action, inside a form that lost its session, or sent to an endpoint where Cloudflare challenges the client before the application ever reads the token.

Each of those failures looks different on the wire. This guide shows how to tell them apart from the response, how to reproduce timeout-or-duplicate with Cloudflare's own test keys, and a submit flow in Python and Node.js that mints one token per request and never reuses it.

Quick diagnosis

What you get back	What it means	Fix
`"error-codes": ["timeout-or-duplicate"]`	The token was already validated once, or it expired	One new token per submit, including retries, posted within seconds
`"error-codes": ["invalid-input-response"]`	Token malformed, truncated, expired, or minted for a different sitekey	Solve for the sitekey on the rendered page and post within seconds
The app says "captcha failed", no error code	The backend compared `hostname` or `action`, or the token went into the wrong field	Pass the exact page URL and the widget's `action`; match the field name
A 403 or 419 page from the app itself	CSRF token, session cookie or hidden fields missing	GET the form in the same session and send every hidden input
Header `cf-mitigated: challenge`	Cloudflare challenged the client; the app never saw your token	Get `cf_clearance` and reuse it with the same IP, User-Agent and TLS fingerprint
`Error 1020` or "Sorry, you have been blocked"	A firewall rule matched the request	No token changes this

The rest of the article explains each row and ends with code that handles all of them.

How Turnstile validation works, and why the browser succeeds

A Turnstile token is a one-time proof, up to 2,048 characters long, that the widget produced for one sitekey on one hostname. The flow has three steps:

The widget runs in the page and writes the token into a hidden input named cf-turnstile-response (a site can rename it with data-response-field-name).
The form is submitted, and the site's backend sends the token and its secret key to https://challenges.cloudflare.com/turnstile/v0/siteverify.
Siteverify answers with success, error-codes, challenge_ts, hostname, action and cdata. The backend decides what to do with that answer.

Three rules from Cloudflare's server-side validation docs drive every failure below:

A token is valid for 300 seconds from generation.
A token can be validated once. A replayed token is rejected with timeout-or-duplicate.
A token is at most 2,048 characters. Anything that truncates it (a fixed-width column, a log line you copied it from) makes it invalid.

The browser gets all of this right by default. It submits once, seconds after the token was minted, from the page that minted it, with the cookies and hidden fields the form expects. The widget also refreshes an expired token on its own (refresh-expired defaults to auto). A script that copies the token out of the page loses all of that.

One more thing to keep in mind: you never talk to siteverify. The backend does. Whether you see the raw error-codes, a generic "verification failed" message, or a bare 403 depends entirely on how that backend was written.

Step 1: classify the failing response

Before changing anything, find out which layer rejected the request. This function looks at the response in the order that matters:

import re

BLOCK_PAGE = re.compile(r"error(?: code)?:? ?10\d\d|sorry, you have been blocked", re.I)


def diagnose(resp):
    """Return which layer rejected a form POST."""
    if resp.headers.get("cf-mitigated") == "challenge":
        return "cloudflare-challenge"      # Cloudflare answered; the app never saw the token
    if BLOCK_PAGE.search(resp.text[:5000]):
        return "cloudflare-block"          # WAF rule such as 1020; no token helps
    try:
        body = resp.json()
    except ValueError:
        body = None
    codes = body.get("error-codes") if isinstance(body, dict) else None
    if codes:
        return "token-rejected: " + ",".join(codes)
    if resp.status_code in (400, 401, 403, 419, 422):
        return "app-rejected"              # CSRF/session/fields, or a token error the app hides
    return "ok" if resp.ok else f"http-{resp.status_code}"

Call it as print(resp.status_code, diagnose(resp)) right after the failing POST. Typical output for the three most common cases:

403 cloudflare-challenge
200 token-rejected: timeout-or-duplicate
403 app-rejected

Don't use the server: cloudflare or cf-ray headers for this. Every response from a proxied site carries them, including the application's own 403 pages. cf-mitigated: challenge is the header Cloudflare documents for challenge pages, and it is the reliable signal.

Step 2: reproduce the error codes with Cloudflare's test keys

If you own the backend, or you want a test for your client's retry logic, Cloudflare publishes test keys. Test sitekeys make the widget return the dummy token XXXX.DUMMY.TOKEN.XXXX, and test secret keys make siteverify return a fixed answer:

import requests

VERIFY = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
TEST_SECRETS = {
    "always passes": "1x0000000000000000000000000000000AA",
    "always fails": "2x0000000000000000000000000000000AA",
    "already spent": "3x0000000000000000000000000000000AA",
}

for label, secret in TEST_SECRETS.items():
    r = requests.post(VERIFY, data={"secret": secret, "response": "XXXX.DUMMY.TOKEN.XXXX"}, timeout=30)
    body = r.json()
    print(f"{label:14} success={body['success']} error-codes={body['error-codes']}")

Output:

always passes  success=True error-codes=[]
always fails   success=False error-codes=['invalid-input-response']
already spent  success=False error-codes=['timeout-or-duplicate']

The front-end test sitekeys are 1x00000000000000000000AA (always passes), 2x00000000000000000000AB (always fails) and 3x00000000000000000000FF (forces an interactive challenge). Production secret keys reject the dummy token, so pair test sitekeys with test secrets.

Cause 1: the token was already used (timeout-or-duplicate)

Cloudflare's docs describe timeout-or-duplicate as "Token has already been validated". Scripts usually spend a token twice in one of these ways:

The browser submitted it first. Playwright clicks Submit, or the page submits itself from the widget callback, and then your script reads the token from the DOM and replays it with requests.
Retry logic resends the same payload. A tenacity decorator or a for attempt in range(3) loop around session.post(url, data=form) retries with the old token still inside form. The first attempt may have reached siteverify even though it timed out on your side.
A validation call you didn't notice. Some front ends validate the token with an XHR request when the widget completes and then post the form. If your script repeats both requests with one token, siteverify sees it twice. The Network tab in DevTools shows these calls.
A shared token pool. Several workers read tokens from one queue and two of them get the same one.
Testing by hand. Pasting the token into curl to see whether it works uses it up.

The fix is a rule, not a setting: a token belongs to exactly one HTTP request. Every retry mints a new one.

Cause 2: the token expired after 300 seconds (timeout-or-duplicate or invalid-input-response)

The 300 seconds run from generation, not from the moment your code received the token. A token from a solver has already aged a little by the time your poll picks it up, and a pipeline that prepares tokens ahead of time burns the rest.

Cloudflare's docs name both codes for an expired token: the error-code table lists expiry under invalid-input-response ("Token is invalid, malformed, or expired"), while the same page says a token submitted after five minutes fails with timeout-or-duplicate. Backends also pass through different codes. Treat both the same way: request a fresh token instead of debugging the old one.

The simplest guard is ordering. Fetch the form, build the payload, and solve last, so the only thing between the solve and the POST is one function call. If your flow has a slow step you cannot move, check the token's age before you send it:

import time

TOKEN_BUDGET = 120   # seconds; well inside the 300 s lifetime

# solve_turnstile() is defined in the full flow further down
token, received_at = solve_turnstile(SITEKEY, FORM_URL, ACTION), time.monotonic()
payload = build_payload()                        # stands in for the slow step you can't move
if time.monotonic() - received_at > TOKEN_BUDGET:
    token, received_at = solve_turnstile(SITEKEY, FORM_URL, ACTION), time.monotonic()

Cause 3: the sitekey, hostname or action don't match

A token is minted for one widget configuration. Check these four things:

Multiple widgets. A login form and a newsletter form on the same page can use different sitekeys. Solve for the widget inside the form you submit.
Sitekeys set by JavaScript. When a site calls turnstile.render('#el', { sitekey: ... }), the key is not in the static HTML, and it can change between deploys. Read it from the rendered page, not from a requests.get of the HTML.
The page URL. Pass the URL of the page that shows the widget, not the POST endpoint or the site root. Siteverify returns the hostname the token was issued on, and a backend may compare it.
The action. A widget can carry data-action (up to 32 characters: letters, digits, _ and -). Siteverify returns it, and a backend that checks it rejects a token minted without it or with a different value.

This Playwright snippet reads all of it from the rendered widget, including a renamed response field:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://target.example/login", wait_until="networkidle")
    widget = page.evaluate("""() => {
        const el = document.querySelector('.cf-turnstile, [data-sitekey]');
        return el && {
            sitekey: el.dataset.sitekey,
            action: el.dataset.action || null,
            field: el.dataset.responseFieldName || 'cf-turnstile-response',
        };
    }""")
    print(widget)
    browser.close()

Expected output:

{'sitekey': '0x4AAAAAAA...', 'action': 'login', 'field': 'cf-turnstile-response'}

If it prints None, the site renders the widget from JavaScript without data attributes. Search the page's scripts for turnstile.render( and read the sitekey and action from the options object.

Cause 4: the 403 comes from the form, not from Turnstile

This one is easy to miss because the token gets the blame. A browser form carries more than the token, and a script that sends only cf-turnstile-response plus the visible fields usually drops something:

A CSRF token in a hidden input, tied to a session cookie the browser received when it loaded the page. Django answers a CSRF failure with 403, Laravel with 419.
Session cookies set by the GET of the form page.
Other hidden inputs: form IDs, timestamps, honeypot fields that must stay empty.
The encoding. An endpoint that the browser calls with a JSON fetch may reject application/x-www-form-urlencoded, and the reverse is also true.
The field name. data-response-field-name renames cf-turnstile-response, and some front ends move the token into a JSON key or a header before sending.

The fastest check is to open DevTools, find the browser's successful request in the Network tab, use "Copy as cURL", and diff it against what your script sends. Then load the form with the same session you post with. The full flow below does that with a small stdlib parser:

from html.parser import HTMLParser


class _HiddenInputs(HTMLParser):
    def __init__(self):
        super().__init__()
        self.fields = {}

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "input" and (a.get("type") or "").lower() == "hidden" and a.get("name"):
            self.fields[a["name"]] = a.get("value") or ""


def hidden_inputs(html):
    """Every hidden input in the page: CSRF token, form IDs, honeypots."""
    parser = _HiddenInputs()
    parser.feed(html)
    return parser.fields

If the page has more than one form, feed the parser only the HTML of the form you submit, so another form's hidden fields don't end up in your payload.

Cause 5: Cloudflare challenges the client before the app sees the token

If the response has cf-mitigated: challenge, Cloudflare answered on the site's behalf. The request never reached the application, so the token in your body was never checked. This happens when the site puts a managed challenge in front of the endpoint, and a plain requests client, with its default TLS fingerprint and no cf_clearance cookie, is exactly the kind of client that challenge is set up to stop.

A better Turnstile token won't fix this. You need the clearance cookie, sent the way the browser that earned it sent it:

from curl_cffi import requests as cffi   # pip install curl_cffi

session = cffi.Session(impersonate="chrome")        # Chrome-like TLS and HTTP/2 fingerprint
session.headers["User-Agent"] = BROWSER_UA          # the exact UA that received cf_clearance
session.cookies.set("cf_clearance", CF_CLEARANCE, domain=".target.example")

resp = session.post(POST_URL, data=payload, timeout=30)
print(resp.status_code, resp.headers.get("cf-mitigated"))

Take BROWSER_UA and CF_CLEARANCE from the same browser session (in Playwright, page.evaluate("navigator.userAgent") and context.cookies()), and send the request from the same IP. When the clearance stops working you will see cf-mitigated: challenge again, which means "get a new cookie", not "retry". I went through the difference between the two challenge types in managed vs interactive Cloudflare challenge: how to tell from the response, and the cookie's lifecycle in why cf_clearance expires and how to stop the re-challenge loop.

Cause 6: a firewall rule, not a captcha

Error 1020 ("Access denied") or a "Sorry, you have been blocked" page with a Ray ID means a WAF rule matched the request: an IP range, a country, a path or a request rate. There is no challenge to complete, so no token or cookie changes the result. Slow down, check whether the site offers an API for what you need, or ask the site owner.

The fixed flow in Python

This puts the pieces together: load the form in a session, solve last, post immediately, classify the response, and mint a new token if the token layer rejected it. The solve step uses a 2Captcha-style in.php/res.php token API; action is an optional parameter, sent only when the widget has one.

Prerequisites: Python 3.9+, pip install requests. Inputs: the page URL, the POST URL, and the sitekey, action and field name from Cause 3. It reuses diagnose() from Step 1 and hidden_inputs() from Cause 4.

import time

import requests

API_KEY = "YOUR_API_KEY"
SOLVER = "https://ocr.captchaai.com"        # 2Captcha-style in.php / res.php API
FORM_URL = "https://target.example/login"   # the page that shows the widget
POST_URL = "https://target.example/login"   # where the form posts
SITEKEY = "0x4AAAAAAA..."                   # from the rendered widget
ACTION = None                               # the widget's data-action, if it has one
TOKEN_FIELD = "cf-turnstile-response"       # or the widget's data-response-field-name

RETRYABLE = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


class SolveError(RuntimeError):
    pass


def check_config():
    if API_KEY == "YOUR_API_KEY" or "..." in SITEKEY or "target.example" in FORM_URL + POST_URL:
        raise SystemExit("Fill in API_KEY, SITEKEY, FORM_URL and POST_URL before running.")


def _call(method, url, **kw):
    """One solver API call, with backoff on network and transient server errors."""
    err = None
    for attempt in range(4):
        if attempt:
            time.sleep(min(30, 5 * 2 ** attempt))   # 10 s, 20 s, 30 s
        try:
            body = requests.request(method, url, timeout=30, **kw).json()
        except (requests.RequestException, ValueError) as exc:
            err = type(exc).__name__        # not str(exc): it can contain the URL and key
            continue
        if body.get("status") == 1 or body.get("request") not in RETRYABLE:
            return body
        err = body["request"]
    raise SolveError(f"solver unreachable: {err}")


def solve_turnstile(sitekey, pageurl, action=None, timeout=120):
    data = {"key": API_KEY, "method": "turnstile", "sitekey": sitekey,
            "pageurl": pageurl, "json": 1}
    if action:
        data["action"] = action
    sub = _call("POST", f"{SOLVER}/in.php", data=data)
    if sub["status"] != 1:
        # ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE, ERROR_WRONG_SITEKEY, ERROR_PAGEURL, ...
        raise SolveError(f"submit rejected: {sub['request']}")

    deadline = time.monotonic() + timeout
    time.sleep(15)
    while time.monotonic() < deadline:
        res = _call("GET", f"{SOLVER}/res.php",
                    params={"key": API_KEY, "action": "get", "id": sub["request"], "json": 1})
        if res["status"] == 1:
            return res["request"]
        if res["request"] != "CAPCHA_NOT_READY":
            raise SolveError(f"solve failed: {res['request']}")   # e.g. ERROR_CAPTCHA_UNSOLVABLE
        time.sleep(5)
    raise SolveError(f"no token after {timeout}s")


def submit(fields, max_tokens=2):
    check_config()
    session = requests.Session()
    for attempt in range(1, max_tokens + 1):
        page = session.get(FORM_URL, timeout=30)               # cookies + CSRF for this attempt
        if page.headers.get("cf-mitigated") == "challenge":
            print("form page is behind a Cloudflare challenge: see Cause 5")
            return page, "cloudflare-challenge"                # a token can't help, so don't solve
        payload = {**hidden_inputs(page.text), **fields}
        payload[TOKEN_FIELD] = solve_turnstile(SITEKEY, FORM_URL, ACTION)   # solve last
        resp = session.post(POST_URL, data=payload, timeout=30)             # post immediately
        verdict = diagnose(resp)
        print(f"attempt {attempt}: HTTP {resp.status_code} {verdict}")
        if not verdict.startswith("token-rejected"):
            return resp, verdict
        # that token is spent either way: loop and mint a new one, never resend it
    return resp, verdict


if __name__ == "__main__":
    submit({"username": "your-user", "password": "your-password"})

Expected output on success:

attempt 1: HTTP 200 ok

When the first token was spent before it arrived (Cause 1), the loop mints a second one instead of resending it:

attempt 1: HTTP 200 token-rejected: timeout-or-duplicate
attempt 2: HTTP 200 ok

And when the POST endpoint sits behind a managed challenge (Cause 5):

attempt 1: HTTP 403 cloudflare-challenge

In that case, replace requests.Session() in submit() with the curl_cffi session from Cause 5. It exposes the same get, post, .text and .json() calls, so nothing else changes.

The same flow in Node.js

Node 20+, no dependencies (built-in fetch). Save as submit.mjs and run node submit.mjs.

const API_KEY = "YOUR_API_KEY";
const SOLVER = "https://ocr.captchaai.com";
const FORM_URL = "https://target.example/login";
const POST_URL = "https://target.example/login";
const SITEKEY = "0x4AAAAAAA...";
const ACTION = null;
const TOKEN_FIELD = "cf-turnstile-response";
const RETRYABLE = new Set(["ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(url, init = {}) {
  let err;
  for (let attempt = 0; attempt < 4; attempt++) {
    if (attempt) await sleep(Math.min(30_000, 5_000 * 2 ** attempt)); // 10 s, 20 s, 30 s
    try {
      const res = await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) });
      const body = await res.json();
      if (body.status === 1 || !RETRYABLE.has(body.request)) return body;
      err = body.request;
    } catch (e) {
      err = e.name; // not e.message: it can contain the URL and key
    }
  }
  throw new Error(`solver unreachable: ${err}`);
}

async function solveTurnstile(sitekey, pageurl, action, timeoutMs = 120_000) {
  const form = new URLSearchParams({ key: API_KEY, method: "turnstile", sitekey, pageurl, json: "1" });
  if (action) form.set("action", action);
  const sub = await call(`${SOLVER}/in.php`, { method: "POST", body: form });
  if (sub.status !== 1) throw new Error(`submit rejected: ${sub.request}`);

  const deadline = Date.now() + timeoutMs;
  await sleep(15_000);
  while (Date.now() < deadline) {
    const q = new URLSearchParams({ key: API_KEY, action: "get", id: sub.request, json: "1" });
    const res = await call(`${SOLVER}/res.php?${q}`);
    if (res.status === 1) return res.request;
    if (res.request !== "CAPCHA_NOT_READY") throw new Error(`solve failed: ${res.request}`);
    await sleep(5_000);
  }
  throw new Error(`no token after ${timeoutMs / 1000}s`);
}

const ENTITIES = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">" };
const decode = (s) =>
  s.replace(/&(?:#(\d+)|#x([\da-f]+)|(amp|quot|apos|lt|gt));/gi, (_, dec, hex, name) =>
    name ? ENTITIES[name.toLowerCase()] : String.fromCodePoint(dec ? Number(dec) : parseInt(hex, 16)));

function attr(tag, name) {
  // quoted or unquoted attribute value; the leading \s keeps data-name from matching name
  const m = tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i"));
  return m ? decode(m[1] ?? m[2] ?? m[3]) : undefined; // "a&amp;b" in HTML is "a&b" on the wire
}

function hiddenInputs(html) {
  const out = {};
  for (const tag of html.match(/<input\b[^>]*>/gi) ?? []) {
    if (attr(tag, "type")?.toLowerCase() !== "hidden") continue;
    const name = attr(tag, "name");
    if (name) out[name] = attr(tag, "value") ?? "";
  }
  return out;
}

function diagnose(res, text) {
  if (res.headers.get("cf-mitigated") === "challenge") return "cloudflare-challenge";
  if (/error(?: code)?:? ?10\d\d|sorry, you have been blocked/i.test(text.slice(0, 5000))) {
    return "cloudflare-block";
  }
  let codes = [];
  try {
    codes = JSON.parse(text)["error-codes"] ?? [];
  } catch {}
  if (Array.isArray(codes) && codes.length) return `token-rejected: ${codes.join(",")}`;
  if ([400, 401, 403, 419, 422].includes(res.status)) return "app-rejected";
  return res.ok ? "ok" : `http-${res.status}`;
}

async function submit(fields, maxTokens = 2) {
  let verdict;
  for (let attempt = 1; attempt <= maxTokens; attempt++) {
    const page = await fetch(FORM_URL, { signal: AbortSignal.timeout(30_000) });
    if (page.headers.get("cf-mitigated") === "challenge") {
      console.log("form page is behind a Cloudflare challenge: see Cause 5");
      return "cloudflare-challenge"; // a token can't help, so don't solve
    }
    const cookie = page.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
    const payload = new URLSearchParams({ ...hiddenInputs(await page.text()), ...fields });
    payload.set(TOKEN_FIELD, await solveTurnstile(SITEKEY, FORM_URL, ACTION)); // solve last
    const res = await fetch(POST_URL, {
      method: "POST",
      body: payload,
      headers: cookie ? { cookie } : {},
      signal: AbortSignal.timeout(30_000),
    });
    verdict = diagnose(res, await res.text());
    console.log(`attempt ${attempt}: HTTP ${res.status} ${verdict}`);
    if (!verdict.startsWith("token-rejected")) return verdict;
  }
  return verdict;
}

if (API_KEY === "YOUR_API_KEY" || SITEKEY.includes("...") || (FORM_URL + POST_URL).includes("target.example")) {
  console.error("Fill in API_KEY, SITEKEY, FORM_URL and POST_URL before running.");
  process.exit(1);
}
await submit({ username: "your-user", password: "your-password" });

The output format is the same as the Python version:

attempt 1: HTTP 200 ok

Checklist

Response classified first: cf-mitigated, a 1020 page, error-codes, or an error page from the app.
One token per HTTP request, retries included. Nothing else (the browser, a validation XHR, another worker) used it first.
Posted within seconds of the solve, with nothing slow in between.
Sitekey, action and field name read from the rendered widget; pageurl is the page that shows it.
Form loaded in the same session: cookies, CSRF token and every hidden input sent, with the same encoding the browser uses.
If challenged: cf_clearance sent with the same User-Agent and IP, and a browser-like TLS fingerprint.

FAQ

How long is a Cloudflare Turnstile token valid?
300 seconds from generation, and it can be validated only once. In the browser the widget refreshes it automatically. A script has to request a new one.

What do timeout-or-duplicate and invalid-input-response mean?
timeout-or-duplicate means siteverify has already seen this token: something in your flow used it before your request did, or a retry sent it again. Cloudflare's docs also return it for a token older than 300 seconds. invalid-input-response means the token is invalid, malformed or expired, so request a fresh one and post it within seconds.

Why does the same token work in the browser?
The browser submits it once, seconds after it was minted, from the page that minted it, with the form's cookies and hidden fields. If the site also runs a managed challenge, the browser already holds the cf_clearance cookie and the fingerprint Cloudflare accepted.

Can I reuse one Turnstile token across requests or threads?
No. One token, one siteverify call. Budget one solve per submit.

Is the field always called cf-turnstile-response?
It is the default. A site can rename it with data-response-field-name, or its JavaScript can send the token in a JSON body or a header. Copy the browser's real request to be sure.

Disclosure: the solver endpoint in these examples is CaptchaAI, which I run. If you want to try this flow against your own form, there is one thread free for 30 days, no card, and the Cloudflare Turnstile guide covers the request format and error codes. Whichever solver you use, the rule is the same: read the response first, then give every request its own fresh token.

reCAPTCHA v3 score stuck at 0.1 or 0.3? What drives it and how to raise it

Bassem Shahin — Thu, 25 Jun 2026 08:14:51 +0000

If your Selenium, Playwright or Puppeteer run keeps getting a reCAPTCHA v3 score of 0.1 or 0.3, reCAPTCHA decided the session looked automated before you submitted anything. v3 has no puzzle. It gives the site a number between 0.0 and 1.0, and the site's backend compares that number to its own threshold. The score comes from what reCAPTCHA sees when the page calls grecaptcha.execute(): mostly the IP address, the browser session and the signals the browser exposes. To raise it, change those inputs one at a time and measure after each change. The action name doesn't move it, and neither does the HTTP request that carries the token.

Below: how the score travels from Google to the site, why you only ever see four values, a Python and Node script that prints the score your setup gets on Google's own demo page, and the fixes in the order worth trying.

How a v3 score gets from Google to the site

The page loads https://www.google.com/recaptcha/api.js?render=SITEKEY.
On some event (page load, a click, a submit) it calls grecaptcha.execute(SITEKEY, {action: 'login'}). In the Network tab, the token comes back from a request to /recaptcha/api2/reload.
The page's JavaScript sends the token to its own backend: a form field, a JSON body, a header. Every site does this differently.
The backend POSTs its secret key and the token to https://www.google.com/recaptcha/api/siteverify.
It compares the score in Google's answer to its threshold and, if it's written carefully, checks that action is the one it expected. Google's docs suggest 0.5 as a default threshold. Each site picks its own.

The siteverify answer for a v3 token looks like this:

{
  "success": true,
  "score": 0.3,
  "action": "login",
  "challenge_ts": "2026-09-29T08:12:03Z",
  "hostname": "example.com",
  "error-codes": []
}

Three things follow from that flow:

You never see the score on someone else's site. You see the outcome: a 403, a "verification failed" message, an extra email or SMS step. So measure it somewhere that shows you the number.
Nobody can ask Google for a score. Not you, and not a solving service. The site owns the threshold.
The score belongs to the token. It's fixed by what the browser looked like when execute() ran. Your HTTP client never talks to reCAPTCHA in a v3 flow, so changing the headers or the TLS fingerprint of the request that carries the token doesn't change the number. That request can still trip the site's other checks, but that's a separate problem.

Why it's always 0.1, 0.3, 0.7 or 0.9

Google's reCAPTCHA docs say scores come in 11 levels from 0.0 to 1.0. Only four of them, 0.1, 0.3, 0.7 and 0.9, are returned until the site owner adds a billing account to the Google Cloud project behind their key. Most sites never do, so almost every score you'll see is one of those four.

That changes how you read a result. "Stuck at 0.1" means the lowest bucket, and 0.3 is one bucket up. Against the suggested 0.5 threshold, 0.1 and 0.3 both fail and 0.7 and 0.9 both pass. There's no slow climb to watch: a change either moves you across the line or it doesn't.

Measure your score before you change anything

Google runs a public v3 demo at recaptcha-demo.appspot.com. The page calls execute() on load, sends the token to its own backend, and shows Google's verification answer, score included. That makes it a free, safe score meter for any browser setup. This script opens it with Playwright, catches the verification response and prints the score next to navigator.webdriver, which is true in a browser driven by Playwright, Selenium or Puppeteer with default settings.

# v3_score.py: print the reCAPTCHA v3 score a browser setup gets on Google's demo page.
# pip install playwright && playwright install chromium
from playwright.sync_api import sync_playwright

DEMO = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php"


def measure(headless=True, channel=None, profile_dir=None, proxy=None):
    """proxy looks like {"server": "http://host:port", "username": "...", "password": "..."}"""
    opts = {"headless": headless, "channel": channel, "proxy": proxy}
    with sync_playwright() as p:
        if profile_dir:  # a saved profile keeps cookies and history between runs
            context = p.chromium.launch_persistent_context(profile_dir, **opts)
        else:
            context = p.chromium.launch(**opts).new_context()
        try:
            page = context.new_page()
            # The demo also loads enterprise.js. When that one initialises first, the
            # page's v3 execute() never resolves, so block it: v3 only needs api.js.
            page.route("**/recaptcha/enterprise.js*", lambda route: route.abort())
            # the page calls grecaptcha.execute() on load, then sends the token here
            with page.expect_response(lambda r: "recaptcha-v3-verify.php" in r.url,
                                      timeout=30_000) as verify:
                page.goto(DEMO)
            result = verify.value.json()
            return {"score": result.get("score"), "success": result.get("success"),
                    "errors": result.get("error-codes"),
                    "webdriver": page.evaluate("navigator.webdriver")}
        finally:
            context.close()


if __name__ == "__main__":
    setups = {
        "headless": {"headless": True},
        "headed": {"headless": False},
        "headed Chrome, saved profile": {"headless": False, "channel": "chrome",
                                         "profile_dir": "./v3-profile"},
    }
    for name, opts in setups.items():
        try:
            print(f"{name:30}", measure(**opts))
        except Exception as exc:  # no token in 30 s, missing Chrome channel, dead proxy...
            print(f"{name:30}", "failed:", str(exc).splitlines()[0])

My run on 2026-09-29, from a consumer broadband line:

headless                       {'score': 0.9, 'success': True, 'errors': [], 'webdriver': True}
headed                         {'score': 0.9, 'success': True, 'errors': [], 'webdriver': True}
headed Chrome, saved profile   {'score': 0.9, 'success': True, 'errors': [], 'webdriver': True}

Every setup scored 0.9, including plain headless Chromium with navigator.webdriver set to true. Sixteen back-to-back page loads from the same IP also all came back 0.9. From a clean residential IP, neither the automation flag nor the load rate pulled the score down on this page. That's why the IP is the first thing to test, not the last.

Why block enterprise.js? Without that line, most of my repeat loads never produced a token at all: the page's Enterprise setup took over and its v3 execute() call never resolved. Blocking the file made 16 loads out of 16 work. It only affects the demo page, not the score.

The same measurement in Node:

// v3-score.mjs: the same measurement in Node. npm i playwright && npx playwright install chromium
import { chromium } from "playwright";

const DEMO = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php";

async function measure({ headless = true, channel, profileDir, proxy } = {}) {
  const opts = { headless, channel, proxy }; // proxy: { server, username, password }
  const browser = profileDir ? null : await chromium.launch(opts);
  const context = profileDir
    ? await chromium.launchPersistentContext(profileDir, opts) // keeps cookies between runs
    : await browser.newContext();
  try {
    const page = await context.newPage();
    // the demo also loads enterprise.js, which can stop its v3 execute() from resolving
    await page.route("**/recaptcha/enterprise.js*", (route) => route.abort());
    const [response] = await Promise.all([
      page.waitForResponse((r) => r.url().includes("recaptcha-v3-verify.php"), { timeout: 30_000 }),
      page.goto(DEMO),
    ]);
    const result = await response.json();
    const webdriver = await page.evaluate(() => navigator.webdriver);
    return { score: result.score, success: result.success, errors: result["error-codes"], webdriver };
  } finally {
    await context.close();
    await browser?.close();
  }
}

const setups = {
  "headless": { headless: true },
  "headed": { headless: false },
  "headed Chrome, saved profile": { headless: false, channel: "chrome", profileDir: "./v3-profile" },
};
for (const [name, opts] of Object.entries(setups)) {
  try {
    console.log(name.padEnd(30), await measure(opts));
  } catch (err) { // no token in 30 s, missing Chrome channel, dead proxy...
    console.log(name.padEnd(30), "failed:", err.message.split("\n")[0]);
  }
}

headless                       { score: 0.9, success: true, errors: [], webdriver: true }
headed                         { score: 0.9, success: true, errors: [], webdriver: true }
headed Chrome, saved profile   { score: 0.9, success: true, errors: [], webdriver: true }

One caveat. Google says reCAPTCHA learns from each site's own traffic, so a 0.9 on the demo doesn't promise a 0.9 on your target. The demo is for comparing setups. If the same script scores 0.9 on your laptop and 0.1 on your CI runner, you've found your variable.

What pushes the score down

Google doesn't publish the model's inputs. These are the signals that keep coming up, and how to test each one with the script above:

Signal	What tends to lower it	How to test it
IP reputation	cloud and datacenter ranges, busy shared proxies, VPN exits	run the script on the machine where the job runs, then from a home connection, and compare
Session history	a fresh, empty profile on every run	compare `profile_dir=None` with a saved profile on its second and third run
Automation signals	headless and automation markers the page can read	compare headless with headed, and bundled Chromium with `channel="chrome"`

Google's docs also say v3 looks at how users interact with the site. That's the hardest signal to measure, so leave it until the three above are settled.

One thing that does not lower the score is the action name. To check, I called execute() on the demo with action: 'login' and sent the token to the demo's backend, which expects examples/v3scores. You can repeat it in Chrome. Open the demo with DevTools open, right-click the enterprise.js request in the Network tab, choose Block request URL, reload, and paste this into the console:

// DevTools console on the demo page (enterprise.js blocked, page reloaded)
const key = "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9";
for (const action of ["examples/v3scores", "login"]) {
  const token = await grecaptcha.execute(key, { action });
  const res = await fetch("/recaptcha-v3-verify.php?action=examples/v3scores&token=" + token);
  const { success, score, "error-codes": errors } = await res.json();
  console.log(action, JSON.stringify({ success, score, errors }));
}

examples/v3scores {"success":true,"score":0.9,"errors":[]}
login {"success":false,"score":0.9,"errors":["action-mismatch"]}

The score stayed at 0.9 and the token was rejected anyway. A wrong action gets the token turned away without touching the score. So copy the exact string the page passes to execute() (Google allows only letters, digits, slashes and underscores) instead of guessing a "better" one.

How to raise it, in order

Get a baseline. Run the measuring script from the same machine, network and browser setup your job uses. If that already scores 0.7 or 0.9 and the site still refuses you, the score isn't the problem. Skip to "When the score isn't the problem" below.
Change the IP first. If the job runs in a cloud region, measure again through a residential or mobile connection in the country the site's real users are in. In my runs the automation flag made no difference from a clean IP, which points at the IP as the bigger lever. It's also one argument to test (proxy=).
Keep the session. Use a persistent profile (launch_persistent_context in Python, launchPersistentContext in Node) so cookies and history survive between runs, instead of a new empty context every time.
Try a real browser build, headed. channel="chrome" drives the installed Google Chrome instead of the bundled Chromium. Measure, and keep it only if the number moves.
Re-measure after every change. With four buckets, a change either crosses the site's threshold or it doesn't. Keep the ones that do and drop the rest, so you don't carry a pile of tweaks that never helped.

If it's your own site

If the low scores are hitting your own end-to-end tests, don't try to make the test browser look human. Google's FAQ says to create a separate key for testing environments because scores there "may not be accurate", and the v3 docs warn that staging scores can differ from production. Use a test key in staging and mock the siteverify call in the test environment, so the suite never depends on a score. If real users are getting 0.1 or 0.3, Google suggests running v3 without acting on the score at first. Log score and action for a while, then pick the threshold from your own traffic.

When the score isn't the problem

Action mismatch. Shown above. Copy the string exactly, including case and slashes.
Expired or reused token. Per Google's docs, a token is valid for two minutes and can be verified once. siteverify reports both cases as timeout-or-duplicate. Get a fresh token right before the request that uses it.
It isn't v3. A widget with data-size="invisible" is v2 invisible, and v3 parameters won't help against it. I covered how to tell them apart in reCAPTCHA v2 vs v3 vs Enterprise: how to tell which one you're fighting.
Enterprise rules. An Enterprise site gets a fuller assessment and can reject a token over hostname, IP or session rules even when the score is fine.

Getting the token from a solving API instead

Sometimes you've done the fundamentals and the setup still can't reach the site's threshold, or the job runs somewhere you can't put a real browser. The other route is to get the token from a solving service: its browser runs execute(), and you send the token the way the page would. Many services use the 2Captcha-style in.php/res.php API. For v3, the two parameters people forget are version=v3 and action. 2Captcha also takes a min_score, but the endpoint below has no such parameter. The token scores whatever Google gives the solver's session, and the site's threshold still decides.

# get_v3_token.py: fetch a reCAPTCHA v3 token from a 2Captcha-compatible in.php / res.php API
import os
import time

import requests

API = "https://ocr.captchaai.com"
KEY = os.environ.get("CAPTCHA_API_KEY", "YOUR_API_KEY")
TRANSIENT = {"ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR"}


def get_v3_token(sitekey, pageurl, action, timeout=120):
    if KEY in ("", "YOUR_API_KEY"):
        raise SystemExit("Set CAPTCHA_API_KEY first")
    r = requests.post(f"{API}/in.php", timeout=30, data={
        "key": KEY, "method": "userrecaptcha", "version": "v3",  # version=v3 is required
        "googlekey": sitekey, "pageurl": pageurl, "action": action, "json": 1}).json()
    if r["status"] != 1:  # ERROR_WRONG_USER_KEY, ERROR_ZERO_BALANCE, ERROR_WRONG_SITEKEY...
        raise RuntimeError(f"submit rejected: {r['request']}")
    task_id, deadline, delay = r["request"], time.time() + timeout, 5
    time.sleep(15)  # the API's v3 guide says to wait 15-20 s before the first poll
    while time.time() < deadline:
        r = requests.get(f"{API}/res.php", timeout=30, params={
            "key": KEY, "action": "get", "id": task_id, "json": 1}).json()
        if r["status"] == 1:
            return r["request"]
        if r["request"] == "CAPCHA_NOT_READY":
            delay = 5
        elif r["request"] in TRANSIENT:
            delay = min(delay * 2, 30)  # back off, keep polling
        else:  # ERROR_CAPTCHA_UNSOLVABLE, ERROR_WRONG_CAPTCHA_ID...
            raise RuntimeError(f"solve failed: {r['request']}")
        time.sleep(delay)
    raise TimeoutError(f"task {task_id}: no token after {timeout}s")


if __name__ == "__main__":
    page, action = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php", "examples/v3scores"
    started = time.time()
    token = get_v3_token("6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", page, action)
    print(f"token {token[:20]}... in {time.time() - started:.0f}s")
    # the demo's backend runs the verification and returns Google's answer, score included
    check = requests.get("https://recaptcha-demo.appspot.com/recaptcha-v3-verify.php",
                         params={"action": action, "token": token}, timeout=30).json()
    print({k: check.get(k) for k in ("success", "score", "action", "error-codes")})

My run against the demo on 2026-09-29:

token 0cAFcWeA6dVunEBcVyiO... in 16s
{'success': True, 'score': 0.9, 'action': 'examples/v3scores', 'error-codes': []}

Look at the second line. The token was created in the solver's browser and sent to the demo from Python requests, a different client on a different IP, and it still scored 0.9. That's "the score belongs to the token" in practice. The two-minute clock is also already running by the time res.php hands you the token, so use it straight away. The parameters match 2Captcha's, so moving an existing client over is mostly a base-URL change.

FAQ

Can I request a higher reCAPTCHA v3 score?

No. Nothing in reCAPTCHA's flow lets you ask Google for a score, and the API in the last script has no min_score parameter. The site's backend picks the threshold, and the token clears it or doesn't.

Why is my score always exactly 0.1, 0.3, 0.7 or 0.9?

Those are the four levels Google returns unless the site owner has added a billing account to their Google Cloud project, which unlocks all 11.

Does the `action` name change the score?

No. In the test above, the wrong action came back with the same 0.9 plus action-mismatch. The action decides whether the token is accepted, not how it scores.

Will hiding `navigator.webdriver` fix a 0.1?

Not by itself. On a clean IP, my runs scored 0.9 with it set to true. If you're at 0.1 from a datacenter IP, change the IP first and measure again.

Is reCAPTCHA v3 Enterprise scored differently?

It's the same 0.0 to 1.0 idea, loaded through enterprise.js. The site's backend gets a fuller assessment it can apply its own rules to. For a solving API it's the same request plus enterprise=1, and if the API returns a User-Agent with the token, send the token with that User-Agent.

I'm Bassem, and I run CaptchaAI, the ocr.captchaai.com endpoint in the last script. It returns reCAPTCHA v3 and v3 Enterprise tokens for the action you send, and enterprise sites can still apply their own rules, so test against your real target first. A free thread is enough for that: one thread for 30 days, no card. The parameters are in the reCAPTCHA v3 guide.

2Captcha-compatible API: migrate off 2Captcha by changing one base URL (Python diff)

Bassem Shahin — Wed, 24 Jun 2026 08:56:41 +0000

If your scraper or test suite already calls 2Captcha's in.php / res.php API, trying another provider does not need a new integration. Several services accept the same requests and return the same responses (a "2Captcha-compatible API"), so the migration is two values: the base URL and the API key. method=userrecaptcha, googlekey, pageurl, the OK|<id> submit response, CAPCHA_NOT_READY polling and the token you put into g-recaptcha-response all stay the same.

This post covers the exact diff, a small client that makes the provider a config value (Python and Node.js), which reCAPTCHA parameters carry over, the five things that do not, how to point the official 2captcha-python SDK at another host, and an A/B harness so you decide on your own traffic.

Scope: this is about the classic in.php / res.php interface. If your code uses 2Captcha's newer JSON createTask / getTaskResult endpoints, check that the new provider accepts that format before you plan a one-line change.

The diff

 import os

-SOLVER_BASE = "https://2captcha.com"
-SOLVER_KEY = os.environ["TWOCAPTCHA_KEY"]
+SOLVER_BASE = "https://ocr.captchaai.com"
+SOLVER_KEY = os.environ["SOLVER_API_KEY"]

Both hosts serve /in.php and /res.php, so every request built from SOLVER_BASE keeps working. If the base URL is hard-coded in several files, the first real step is to make it one setting. The client below does that, so switching (or switching back) becomes an environment variable instead of a deploy.

A client where the provider is config (Python)

Prerequisites: Python 3.9+, pip install requests, and three environment variables: SOLVER_API_KEY, SITE_KEY (the data-sitekey value, or the k= parameter of the reCAPTCHA anchor URL) and PAGE_URL (the full URL of the page that shows the widget).

# solver_client.py  (Python 3.9+, pip install requests)
import os
import time

import requests

# Worth retrying: the server is busy or briefly failing.
RETRYABLE = {
    "ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR",
    "ERROR_ZERO_BALANCE",       # on thread-based billing this can mean "all threads busy"
    "ERROR_NO_SLOT_AVAILABLE",  # 2Captcha's queue-full code
}


class SolverError(Exception):
    pass


class CompatSolver:
    """Talks the 2Captcha in.php / res.php protocol to any compatible host."""

    def __init__(self, base, api_key, initial_wait=15, poll=5, timeout=120):
        if not api_key or api_key == "YOUR_API_KEY":
            raise ValueError("Set SOLVER_API_KEY to a real key")
        self.base = base.rstrip("/")
        self.key = api_key
        self.initial_wait, self.poll, self.timeout = initial_wait, poll, timeout
        self.http = requests.Session()

    def _call(self, endpoint, params, method="GET"):
        params = {**params, "key": self.key, "json": 1}
        url = f"{self.base}/{endpoint}"
        delay, code = 5, None
        for attempt in range(5):
            if attempt:
                time.sleep(delay)
                delay = min(delay * 2, 30)  # exponential backoff, capped at 30 s
            try:
                if method == "POST":
                    r = self.http.post(url, data=params, timeout=30)
                else:
                    r = self.http.get(url, params=params, timeout=30)
                r.raise_for_status()
                data = r.json()
            except (requests.RequestException, ValueError) as exc:
                code = f"NETWORK: {exc.__class__.__name__}"
                continue
            code = data.get("request")
            if data.get("status") == 1 or code == "CAPCHA_NOT_READY":
                return data
            if code not in RETRYABLE:
                # bad key, bad params, bad proxy, ERROR_CAPTCHA_UNSOLVABLE:
                # sending the same request again will not fix these
                raise SolverError(code)
        raise SolverError(f"gave up after 5 attempts: {code}")

    def solve(self, **task):
        task_id = self._call("in.php", task, method="POST")["request"]
        time.sleep(self.initial_wait)
        deadline = time.monotonic() + self.timeout
        attempt = 0
        while time.monotonic() < deadline:
            attempt += 1
            data = self._call("res.php", {"action": "get", "id": task_id})
            if data.get("status") == 1:
                data.setdefault("request", data.get("result"))  # Enterprise tokens can come back as "result"
                return data  # data["request"] is the token
            print(f"poll {attempt}: not ready")
            time.sleep(self.poll)
        raise SolverError(f"no result after {self.timeout}s (task {task_id})")


if __name__ == "__main__":
    solver = CompatSolver(
        base=os.environ.get("SOLVER_BASE", "https://ocr.captchaai.com"),
        api_key=os.environ.get("SOLVER_API_KEY", "YOUR_API_KEY"),
    )
    result = solver.solve(
        method="userrecaptcha",
        googlekey=os.environ["SITE_KEY"],
        pageurl=os.environ["PAGE_URL"],
        # invisible=1,                   # v2 invisible
        # version="v3", action="login",  # v3: action comes from grecaptcha.execute
    )
    print("token:", result["request"][:40] + "...")

Expected output:

poll 1: not ready
poll 2: not ready
token: 03AHJ_Vuve5Asa4koK3KSMyUkCq0vUFCR5Im4CwB...

What it handles:

json=1 on every call, so every answer is {"status": ..., "request": ...}. Both providers use that shape, with one exception: on the endpoint used here, a solved reCAPTCHA Enterprise task returns the token as result, next to a user_agent field, so solve() copies result into request.
A 15-second wait after submitting, then a poll every 5 seconds, with a 120-second cap.
Network errors, HTTP 5xx and ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR: retried with exponential backoff capped at 30 seconds.
A bad key, bad parameters, a bad proxy or ERROR_CAPTCHA_UNSOLVABLE: raised at once, because repeating the same request will not change the answer. If you want, resubmit an unsolvable task once from the caller.

The same client in Node.js

Node 18 or later has fetch built in, so there are no dependencies. Save it as solver-client.mjs and run node solver-client.mjs with the same environment variables.

// solver-client.mjs  (Node 18+, no dependencies)
const RETRYABLE = new Set([
  "ERROR_SERVER_ERROR", "ERROR_INTERNAL_SERVER_ERROR",
  "ERROR_ZERO_BALANCE", "ERROR_NO_SLOT_AVAILABLE",
]);
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));

class SolverError extends Error {}

class CompatSolver {
  constructor(base, apiKey, { initialWait = 15, poll = 5, timeout = 120 } = {}) {
    if (!apiKey || apiKey === "YOUR_API_KEY") throw new Error("Set SOLVER_API_KEY to a real key");
    Object.assign(this, { base: base.replace(/\/+$/, ""), apiKey, initialWait, poll, timeout });
  }

  async call(endpoint, params, method = "GET") {
    const query = new URLSearchParams({ ...params, key: this.apiKey, json: "1" });
    const url = `${this.base}/${endpoint}` + (method === "GET" ? `?${query}` : "");
    let delay = 5, code;
    for (let attempt = 0; attempt < 5; attempt++) {
      if (attempt) { await sleep(delay); delay = Math.min(delay * 2, 30); }
      let data;
      try {
        const res = await fetch(url, {
          method,
          body: method === "POST" ? query : undefined,
          signal: AbortSignal.timeout(30_000),
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        data = await res.json();
      } catch (err) {
        code = `NETWORK: ${err.message}`;
        continue;
      }
      code = data.request;
      if (data.status === 1 || code === "CAPCHA_NOT_READY") return data;
      if (!RETRYABLE.has(code)) throw new SolverError(code);
    }
    throw new SolverError(`gave up after 5 attempts: ${code}`);
  }

  async solve(task) {
    const taskId = (await this.call("in.php", task, "POST")).request;
    await sleep(this.initialWait);
    const deadline = Date.now() + this.timeout * 1000;
    for (let attempt = 1; Date.now() < deadline; attempt++) {
      const data = await this.call("res.php", { action: "get", id: taskId });
      if (data.status === 1) return { request: data.result, ...data }; // Enterprise tokens can come back as "result"
      console.log(`poll ${attempt}: not ready`);
      await sleep(this.poll);
    }
    throw new SolverError(`no result after ${this.timeout}s (task ${taskId})`);
  }
}

const { SOLVER_BASE, SOLVER_API_KEY, SITE_KEY, PAGE_URL } = process.env;
if (!SITE_KEY || !PAGE_URL) throw new Error("Set SITE_KEY and PAGE_URL");

const solver = new CompatSolver(SOLVER_BASE ?? "https://ocr.captchaai.com", SOLVER_API_KEY);
const result = await solver.solve({ method: "userrecaptcha", googlekey: SITE_KEY, pageurl: PAGE_URL });
console.log(`token: ${result.request.slice(0, 40)}...`);

The output is the same three lines as the Python version.

Which reCAPTCHA parameters carry over

Every variant uses method=userrecaptcha, googlekey and pageurl. The extra parameters are the same names on both sides:

Variant	Extra `in.php` parameters	What to do with the token
v2 checkbox	none	Put it in `g-recaptcha-response`, then submit the form
v2 invisible	`invisible=1` (required; leaving it out can make solves fail)	Same field, then trigger the protected action right away
v2 with a callback	none	Set the field, then call the page's callback function with the token
v3	`version=v3` and `action` (from the page's `grecaptcha.execute` call; `verify` if the page sets none)	Send it in the backend request with the same action
v2 Enterprise	`enterprise=1`, plus `action` if the anchor URL has `sa=`	Poll with `json=1`; the endpoint used here returns the token as `result` plus a `user_agent`, and you submit using that user agent
v3 Enterprise	`version=v3`, `enterprise=1`, `action`	Same user-agent rule; a mismatched user agent fails validation

Not sure which one a site runs? I wrote up how to tell reCAPTCHA v2, v3 and Enterprise apart from the page source: api.js vs enterprise.js, render=, and the execute call.

Five things that do not carry over

min_score on v3. 2Captcha lets you ask for a minimum score. On the endpoint used here it is not a parameter, so remove it. Judge v3 by whether the target accepts the token (the A/B harness below records that).
One error name. 2Captcha's docs call a malformed sitekey ERROR_WRONG_GOOGLEKEY. The error docs for the endpoint used here list it as ERROR_WRONG_SITEKEY. If your code compares error strings, match both, and treat any string you don't recognise as a fatal input error, as the client above does: when I tested, a sitekey of the wrong length came back as the plain message Sitekey length is invalid.
What ERROR_ZERO_BALANCE means. With per-solve billing it means the wallet is empty, so you stop. With thread-based billing, the error docs for the endpoint used here describe it as "insufficient balance/threads" and suggest reducing concurrency and retrying. So it can simply mean you are at your concurrency limit. That is why the client above backs off and retries on it instead of halting.
Proxies. On the endpoint used here, proxy support is off until support enables it for your account, and reCAPTCHA v3 tasks do not take a proxy at all. Strip proxy and proxytype from v3 tasks before you switch.
2Captcha-only extras. soft_id is 2Captcha's developer-attribution ID and means nothing to another provider. If you rely on pingback callbacks, confirm the new provider supports them, or keep polling as the client above does.

Pointing the 2captcha-python SDK at another host

If you use the official 2captcha-python package, you don't need to replace it. I checked the source (twocaptcha/solver.py and twocaptcha/api.py): the constructor takes a server argument, default 2captcha.com, and builds https://{server}/in.php and https://{server}/res.php from it.

import os

from twocaptcha import TwoCaptcha  # pip install 2captcha-python

solver = TwoCaptcha(
    os.environ["SOLVER_API_KEY"],
    server="ocr.captchaai.com",  # hostname only: the SDK adds https:// and /in.php
    softId=None,                 # the default, 4580, is 2Captcha's software-catalog ID
    pollingInterval=5,
)

result = solver.recaptcha(sitekey=os.environ["SITE_KEY"], url=os.environ["PAGE_URL"])
print(result["captchaId"], result["code"][:40])

# v3: pass version and the page's action. Do not pass score=, the SDK sends it as min_score.
# solver.recaptcha(sitekey=..., url=..., version="v3", action="login")

Two details from the source: the SDK always sends version (default v2) and enterprise (default 0), and it raises ApiException with the raw error string, so point 2 above applies to SDK users too. Run one real solve for each variant you use before sending production traffic.

A/B the switch on your own traffic

Don't move everything at once. Keep the old provider, send a fixed share of jobs to the new one, and record what matters: did you get a token, did the target accept it, and how long did it take. A token the target rejects costs you the same as no token, so "accepted" is the number to decide on. The harness reads TWOCAPTCHA_KEY, SOLVER_BASE and SOLVER_API_KEY from the environment and reuses the client above.

# ab_router.py
import hashlib
import os
import statistics
import time

from solver_client import CompatSolver, SolverError

providers = {
    "incumbent": CompatSolver("https://2captcha.com", os.environ["TWOCAPTCHA_KEY"]),
    "candidate": CompatSolver(os.environ["SOLVER_BASE"], os.environ["SOLVER_API_KEY"]),
}
CANDIDATE_PERCENT = 10
stats = {name: {"solved": 0, "failed": 0, "accepted": 0, "secs": []} for name in providers}


def pick(job_id):
    # Same job -> same provider every time, so a retry never mixes providers.
    bucket = int(hashlib.sha256(job_id.encode()).hexdigest(), 16) % 100
    return "candidate" if bucket < CANDIDATE_PERCENT else "incumbent"


def solve_and_submit(job_id, task, submit):
    """submit(token) is your code: post the form, return True if the target accepted it."""
    name = pick(job_id)
    s = stats[name]
    started = time.monotonic()
    try:
        token = providers[name].solve(**task)["request"]
    except SolverError:
        s["failed"] += 1
        raise
    s["solved"] += 1
    s["secs"].append(time.monotonic() - started)
    if submit(token):
        s["accepted"] += 1


def report():
    for name, s in stats.items():
        n = s["solved"] + s["failed"]
        if not n:
            continue
        secs = sorted(s["secs"]) or [float("nan")]  # nan: no successful solve yet
        p95 = secs[int(0.95 * (len(secs) - 1))]
        print(f"{name:9} n={n:5}  token={s['solved'] / n:6.1%}  accepted={s['accepted'] / n:6.1%}"
              f"  median={statistics.median(secs):5.1f}s  p95={p95:5.1f}s")

report() prints one line per provider. The format looks like this (placeholder numbers, not a benchmark):

incumbent n= 1804  token= 96.8%  accepted= 91.2%  median= 21.4s  p95= 47.9s
candidate n=  196  token= 97.4%  accepted= 90.8%  median= 19.6s  p95= 38.2s

Run it for at least a day so peak hours are included, and compare on the sites you actually target. If the candidate holds up, raise CANDIDATE_PERCENT. If it doesn't, 90% of your traffic never left the old provider.

Sizing: per-solve vs per-thread billing

The main reason teams move is cost at volume. Per-solve billing charges for every token. Thread-based billing charges for how many solves can run at the same time, with no limit on the number of solves. So the number you plan around changes from "solves per month" to "solves in progress at peak". Little's law gives it directly:

threads needed ≈ peak solves per second × average seconds per solve

Use your own measured solve time, not a vendor's figure: statistics.mean(stats["candidate"]["secs"]) from the harness gives it. At 2 solves per second and 20 seconds per solve you have about 40 solves in progress; add 20 to 30% headroom for bursts and slow tails and plan for about 50. I worked through the per-1,000 vs thread-based numbers from 10k to 10M solves a month in The real cost of solving reCAPTCHA at scale.

FAQ

Is a 2Captcha-compatible API really a drop-in replacement?

At the protocol level, yes: same endpoints, same parameter names for reCAPTCHA, same OK|<id> and CAPCHA_NOT_READY responses. Check the five points above before you cut over, especially min_score and exact error-string matching.

Do I have to change my token injection code?

No. The token goes into the same place as before: g-recaptcha-response for v2, your backend request for v3, and the page's callback if it uses one. The one addition is for Enterprise: send the request with the user_agent returned alongside the token.

Can I keep 2Captcha as a fallback?

Yes. Because the client takes the base URL and key as arguments, a fallback is a second CompatSolver instance. Catch SolverError from the first and retry the job on the second.

Does this work for Cloudflare Turnstile too?

The same client works; only the task changes (method=turnstile, sitekey, pageurl), and the token goes into cf-turnstile-response. Check the new provider's parameter list for any type you use besides reCAPTCHA.

Trying it

A compatible provider is a drop-in at the API level. Whether it is the right choice depends on acceptance rate, latency and cost on your own traffic, and compatibility is what makes that test cheap.

Disclosure: I work on CaptchaAI, the service behind ocr.captchaai.com in the examples above. If you want to run the A/B without paying for anything, the free thread gives you one thread for 30 days with no card, which is enough for a small test slice. The parameter reference for each reCAPTCHA variant is in the reCAPTCHA v2 guide and the guides linked from it.

The real cost of solving reCAPTCHA at scale (per-1,000 vs thread-based)

Bassem Shahin — Tue, 23 Jun 2026 16:23:28 +0000

The real cost of solving reCAPTCHA at scale

If you automate anything on the public web for long enough, reCAPTCHA is the wall you hit most. It's on far more sites than Turnstile, hCaptcha, or the enterprise bot vendors combined. So when you wire in a solving service, the interesting question usually isn't "can it solve reCAPTCHA" (most can). It's what does it cost when you're doing this 100,000 times a month — or 10 million?

That's where the pricing model matters more than the per-solve price.

Two ways solvers bill you

Per-1,000 solves (usage-based). 2Captcha, Anti-Captcha, CapSolver, CapMonster — most of the market — charge per solve, quoted per 1,000 (~$1–$3 for reCAPTCHA). Your bill scales linearly with volume. Double the traffic, double the cost. Forever.
Thread-based (concurrency-based). A "thread" is one concurrent in-flight solve. You buy N threads and get unlimited solves per thread per month. Cost scales with peak concurrency, not total volume — so once sized, pushing more solves through is free.

The math

reCAPTCHA v2 at ~$2 per 1,000 vs thread-based tiers (illustrative — check current pricing):

|---|---|---|---|---|

| 10,000 | ~$20 | 5 threads | ~$15 | ~$1.50 |

| 100,000 | ~$200 | 5 threads | ~$15 | ~$0.15 |

| 1,000,000 | ~$2,000 | 50 threads | ~$90 | ~$0.09 |

| 10,000,000 | ~$20,000 | 200 threads | ~$300 | ~$0.03 |

The usage column grows in a straight line. The thread column barely moves. At a million/month the effective per-1,000 is single-digit cents; at ten million it's a rounding error.

When each wins

Low/bursty volume → usage-based (or a free tier). A few thousand a month with idle gaps? Pay per solve; you're not paying for concurrency you don't use.
Sustained/high volume → thread-based. Solving continuously? Flat per-thread wins, and the gap widens the more you push.

The one ask of thread-based: size threads to peak concurrency, not total volume. Watch your live concurrency for a day, buy ~that many, done.

The token flow (so this isn't just pricing)

reCAPTCHA v2/v3 is the same three steps regardless of vendor — and on a 2Captcha-compatible API it's identical calls:


import requests, time

API_KEY = "YOUR_KEY"

BASE = "https://ocr.captchaai.com"   # 2Captcha-compatible

r = requests.get(f"{BASE}/in.php", params={

    "key": API_KEY, "method": "userrecaptcha",

    "googlekey": "SITE_KEY", "pageurl": "https://target.example/login"})

task_id = r.text.split("|")[1]

while True:

    res = requests.get(f"{BASE}/res.php", params={"key": API_KEY, "action": "get", "id": task_id})

    if res.text == "CAPCHA_NOT_READY": time.sleep(5); continue

    token = res.text.split("|")[1]; break

# inject token into g-recaptcha-response, submit the form

For v3 the same flow returns a token, but v3 returns a score driven by the session's reputation, not a puzzle — a separate rabbit hole; the cost model is the same either way.

The takeaway

For reCAPTCHA, don't ask the headline per-1,000 rate — ask what your bill looks like at 10× your volume. Usage-based 10×'s with you; thread-based is roughly flat. Size threads to peak concurrency, run the math on your real volume, and pick the model that matches your curve.