A reCAPTCHA v3 token belongs to one page, not to your script
Nothing about v3 happens in the browser, so none of the usual failures show up there either. There is no image to collect and no grid to click. The only thing you get back is a string, and that string is minted against a specific sitekey, a specific page URL and a specific action. The target site's backend checks those before it looks at anything else. A token that looks fine in your log can be thrown away two seconds later on the other side, with nothing in your own process to show for it.
So the productive question is not how good the solver is. It is whether the request that minted the token described the target page correctly.
The field list for a token job
A v3 token is minted with POST /v1/token/recaptcha3. The body is short, and every field in it matters:
-
sitekey— required. The value of thedata-sitekeyattribute on the page you are working against. -
url— required. The docs are blunt about it: it must match the real page. -
useragent— recommended, and not cosmetic. It noticeably improves the pass rate. -
data— the extra-parameters blob. For v3 theactiongoes in here, not at the top level. -
enterprise— sendtrueonly when the target is on reCAPTCHA Enterprise. -
proxy— pins the egress IP. The service expects an object carrying scheme, host, port, username and password. -
type— only needed when the path does not carry the type.
The url is not a formality
If the widget renders on a checkout page, that is the URL to pass — not the home page, and not the login page where your session started. The sitekey and the URL have to belong to the same property; a sitekey borrowed from one site with the URL of another gives the verifier no reason to accept the result.
The useragent has to survive the handoff
Send nothing and the request goes out under the solver's own default UA. Later, your headless browser pastes the token into a form and the backend sees the UA of that browser instead. Grab the UA once from the client that will actually submit the token, keep it in one constant, and pass the same string on every mint.
action goes inside data
Call sites are registered per action name. If the target verifies against an expected action, a v3 token minted with nothing in data.action will not line up with it. Flipping enterprise on is the same kind of mistake in reverse: only set it when the target's front end loads the Enterprise script.
There is no recognition path for v3
The service exposes two entry points and they return different things. /v1/recognition/<type> takes image_data and answers with tiles to click or text to type. /v1/token/<type> takes a sitekey and a URL and answers with something submittable. The pricing table lists recaptcha (image selection) under recognition and recaptcha3 under tokens — v3 has no image, so only the second one applies.
If you would rather not maintain the parameter dance yourself, the same recaptcha v3 flow is what the browser extension drives: you hand it the key, it calls the recognition side and does its own clicking. Driving it from a script means passing sitekey, url and useragent, then spending the token immediately, because it is minted for a session that is already running out.
Poll, do not stampede
Submitting returns a job id: {"data":"nsj_…"}. You then poll GET /v1/token/recaptcha3?id=…. While the job is working you get {"error":14,"message":"Incomplete job"}. That is not a failure, it costs nothing extra, and it is not a reason to submit again. Token jobs are slow — the docs put a measured hCaptcha token at roughly a minute and say to poll every 2–3 seconds, not faster.
The billing rule is what makes blind retries expensive: a rejected submit (bad parameters, no credit, no upstream capacity) is free, but the moment the upstream accepts the job the credits are gone for good, including when it eventually times out. No refunds. A retry loop that fires on every 14 pays two, three, four times for one challenge and runs slower, because the jobs compete with each other.
Token jobs keep their id for 5 minutes; recognition jobs only get 3. Past that the job is void and the only move left is a fresh submit.
Errors that do not arrive as errors
Nearly every failure here comes back with a status code of 200, so branching on the status is a bug. Read the error field:
-
10— invalid request: missing field, wrong method, wrong path. Retrying changes nothing. -
11— rate or concurrency limit. The default ceiling is 4 parallel jobs and 20 requests per second per key. -
13— the job id is unknown or belongs to a different key. -
15— the key is wrong or revoked. -
16— no credit left. Quota refills at midnight Beijing time and does not accumulate. -
9— everything the upstream does not want you to handle separately, including an accepted job that failed or timed out, and an unavailable type.
A misspelled type is worth calling out, because recaptcha3 and recaptcha2 differ by one character, and a typo is forwarded upstream and comes back as 9, which reads like a capacity problem.
Two more things that bite in practice. Python's stdlib urllib is refused by the CDN as a bot, so a plain urllib client sees a failure that has nothing to do with the service — use requests, or give urllib a normal User-Agent header. And the key is not base64: Authorization: Basic nsk_YOUR_KEY takes the raw key right after Basic. Encoding it makes it unrecognisable.
GET /v1/status/ is the cheap sanity check before a run: it returns the remaining credit, the plan's allowance, the seconds until the next reset and the concurrency limit.
A mint-and-poll cycle
import time, requests
BASE = "{base}"
KEY = "nsk_YOUR_KEY"
AUTH = {"Authorization": f"Basic {KEY}"}
def mint_v3(sitekey, page_url, action, ua, timeout=300):
job = requests.post(
f"{BASE}/v1/token/recaptcha3",
headers={**AUTH, "Content-Type": "application/json"},
json={
"sitekey": sitekey,
"url": page_url,
"useragent": ua,
"data": {"action": action},
},
).json()
if "error" in job:
raise RuntimeError(job) # rejected on submit: nothing charged
deadline = time.time() + timeout
while time.time() < deadline:
time.sleep(2.5)
out = requests.get(
f"{BASE}/v1/token/recaptcha3",
headers=AUTH, params={"id": job["data"]},
).json()
if out.get("error") == 14: # still working, keep waiting
continue
if "error" in out: # accepted then failed: charged
raise RuntimeError(out)
return out["data"]
raise TimeoutError(job["data"])
What to check before blaming the solver
- Is the
sitekeythe one on the page that actually renders the widget? - Is
urlthat same page, including the path? - Is
useragentthe UA of the browser that will submit the token? - Does
data.actionmatch the action the call site was registered with? - Are you polling every 2–3 seconds instead of resubmitting?
- Is there credit left and is concurrency under 4?
Get those six right and the token usually survives. Get one wrong and you will spend an afternoon tuning a solver that was never the problem.
Top comments (0)