DEV Community

Bob
Bob

Posted on • Originally published at capbypass.pro

reCAPTCHA error codes explained

#recaptcha #webscraping #automation #debugging

When reCAPTCHA breaks, it rarely says why in plain language - you get a short code like invalid-input-response or a red "ERROR for site owner" banner. This post lists the codes you actually hit when automating, what each one means, and whether it is your token or your setup at fault.

where these codes surface

reCAPTCHA errors show up in two places:

  • Server-side, in the error-codes array of the siteverify response (https://www.google.com/recaptcha/api/siteverify). This is what the site you are hitting sees when it validates your token.
  • Client-side, as a rendered banner ("ERROR for site owner: Invalid site key") or a JS console message ("Cannot contact reCAPTCHA").

You usually only control the token you submit, so the useful split is: which codes mean a bad/expired token versus a misconfigured request.

the common codes

  • missing-input-response - no token was sent at all. Your g-recaptcha-response field is empty. Check you actually attached the solved token to the form/body.
  • invalid-input-response - the token is malformed, expired, or already used. v2/v3 tokens are single-use and expire in ~2 minutes. Solve, submit immediately, never reuse.
  • timeout-or-duplicate - the token was valid but submitted too late or twice. Same fix: one token, one request, fast.
  • missing-input-secret / invalid-input-secret - the site's own secret key is missing or wrong. This is server-side config on the target, not something your client can fix.
  • bad-request - the request to siteverify was malformed (wrong content type, garbled body).
  • browser-error / "Cannot contact reCAPTCHA" - the client could not reach Google. Usually a network/proxy issue on the solving side.

And the client-side banners:

  • "Invalid site key" - the websiteKey (siteKey) is wrong for that domain.
  • "Invalid domain for site key" - the siteKey is restricted to a domain you are not on.
  • "Invalid key type" - you are treating a v3 key as v2 or vice versa.

your fault vs the token's fault

Split the list before you debug:

  • Token quality / lifecycle (you can fix): missing-input-response, invalid-input-response, timeout-or-duplicate. Get a fresh token and submit it once, fast.
  • Key / domain config (the target's setup, or your task params): "Invalid site key", "Invalid domain", "Invalid key type", *-input-secret. Re-check the websiteKey and that you picked the right reCAPTCHA version.

A token that verifies but still gets you blocked is a different problem: a low v3 score. That is not an error code at all - the token is valid, the site just set a threshold you did not clear. See why your reCAPTCHA v3 score is low for that.

reCAPTCHA error codes split in two columns: fixable by you (solve fresh, submit once) versus config issue (wrong site key, domain, or key type).

action mismatch (v3)

On reCAPTCHA v3, an action that does not match what the page expects quietly lowers your score (no error code, just a worse number). If the page calls grecaptcha.execute(siteKey, {action: 'login'}), your task must send the same:

curl -s https://api.capbypass.pro/createTask \
  -H 'Content-Type: application/json' \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "ReCaptchaV3Task",
      "websiteURL": "https://example.com/login",
      "websiteKey": "6Lc...your-site-key",
      "pageAction": "login",
      "proxy": "host:port:user:pass"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

solving cleanly with capbypass

A fresh, correctly-scoped token avoids the whole token-fault half of the list. Solve, read gRecaptchaResponse, submit it once:

import os
from capbypass import CapBypass

client = CapBypass(api_key=os.environ["CAPBYPASS_API_KEY"])

result = client.solve({
    "type": "ReCaptchaV2Task",
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc...your-site-key",
    "proxy": "host:port:user:pass",
})

token = result["solution"]["gRecaptchaResponse"]
# attach as g-recaptcha-response, submit right away
Enter fullscreen mode Exit fullscreen mode

CapBypass surfaces its own task-level problems through the errorCode field on the API response (for example ERROR_CAPTCHA_UNSOLVABLE, ERROR_ZERO_BALANCE, ERROR_INVALID_TASK_DATA) - distinct from Google's verify codes above. Full list in the API reference; task schemas in the reCAPTCHA v2 and reCAPTCHA v3 docs.

Bonus: +5% credits on every top-up

New to CapBypass? Apply code WELCOME_2026 at checkout for an extra 5% in credits on every top-up, with no minimum and no expiry. Redeem it on the top-up page and put it toward your first ReCaptchaV2Task solves.

faq

What does invalid-input-response mean?
The token you submitted is malformed, expired, or already used. reCAPTCHA tokens are single-use and expire in about 2 minutes - solve and submit in one quick step.

Is timeout-or-duplicate my fault?
Yes, usually. The token was fine but arrived too late or twice. Use each token exactly once and submit it immediately after solving.

Why do I see "Invalid site key"?
The websiteKey you passed does not match the one the page uses, or it is restricted to another domain. Re-read the siteKey from the live page and confirm the domain.

A token verifies but I still get blocked. Why?
That is not an error code - it is a low v3 score. The token is valid; the site's threshold is higher than the score your request earned. Improve the request (clean IP, matching action) rather than the token.

Originally published on capbypass.pro. CapBypass is an AI-powered captcha-solving API for reCAPTCHA, hCaptcha, Cloudflare Turnstile and AWS WAF.

Top comments (0)