Do You Need a Proxy to Solve reCAPTCHA?

The rule: ProxyLess reCAPTCHA tasks must not carry a proxy

The check is the suffix: isProxyless(task) is task.endsWith('ProxyLess'). Inside the reCAPTCHA branch of the request schema it splits two ways:

• ProxyLess task with a proxy → rejected: ProxyLess tasks must not include a proxy
• Non-ProxyLess reCAPTCHA task without a proxy → rejected: a proxy is required for non-ProxyLess tasks

Both are HTTP 400 with error: "validation_error" and the complaint in an issues array. Branch on issues[].path, not on the prose:

{
  "success": false,
  "error": "validation_error",
  "message": "Request failed validation.",
  "request_id": "...",
  "issues": [
    { "path": "proxy", "message": "ProxyLess tasks must not include a proxy" }
  ]
}

Three pairs: ReCaptchaV2Task, ReCaptchaV3Task and ReCaptchaV3EnterpriseTask, each with a *ProxyLess twin. Same solve, different egress.

That rule lives in the reCAPTCHA branch only. The other task families return before it with their own rules: EvaluateTask requires a proxy and has no ProxyLess variant; KasadaLogin requires one because its token is IP-bound; KasadaReload needs none and, unlike a ProxyLess task, is not rejected for carrying one; TicketmasterTmptTask treats it as optional, falling back to the solver's own pool. Don't generalize the suffix convention across families.

Why the IP the token is minted from matters

A reCAPTCHA v3 token resolves to a score when your backend verifies it, and that score reflects the context it was minted in — including the network. Your ProxyLess solve egresses from KagedCap's addresses; your proxied solve egresses from yours.

The mismatch shows up at verification, because Google's verification APIs accept a second IP: siteverify takes an optional remoteip, and reCAPTCHA Enterprise's createAssessment takes event.userIpAddress. If your backend passes the address of the request that replayed the token while the token was minted somewhere unrelated, you have given the assessment two unrelated addresses for what is supposed to be one client — and the score reflects that. Not a broken token; a weaker one, by an amount set by the sitekey's configuration and the site's own risk model, neither of which you can see from outside. A v3 token is valid for about two minutes, so there is no rerouting it after the fact.

Measure it rather than trusting anyone's claim, ours included. Send your reCAPTCHA secretKey on the solve request and the response carries a verified score; run the same sitekey and action both ways on a property you own and compare.

When to send your own proxy, and when ProxyLess is fine

Send your own proxy when:

• The token gets replayed from a specific address — a session already established from that exit, or a workflow pinned to one residential IP. The mint and the replay are the same client; make the egress match.
• Your backend passes remoteip or event.userIpAddress at verification.
• The page's behaviour is geography-dependent and you need a particular region.

ProxyLess is fine when:

• You are evaluating the API and don't want to wire up egress first.
• The token is consumed by something that never sees or forwards a client IP.
• It's v2 invisible, where there is no score to degrade.

Two caveats. The ProxyLess exit address is not yours to control, and it is shared. And ProxyLess is the only reCAPTCHA family whose egress KagedCap supplies, which makes it the one we can shed: under load or egress pressure it returns 503 proxyless_disabled while proxied traffic is untouched. If ProxyLess is your only path, that 503 is an outage for you — build the fallback first: the same request with a proxy field and the suffix dropped.

Proxy formats the KagedCap API accepts

Two shapes, and the difference matters:

scheme://user:pass@host:port      →  http://u:p@1.2.3.4:8888
host:port[:user:pass]             →  1.2.3.4:8888:u:p

URL form accepts http, https, socks5, socks5h and socks4; anything else is refused pre-flight as 400 proxy_invalid, reason disallowed scheme <x>.

The colon form is always parsed as http. It has no scheme slot, so a SOCKS proxy written as host:port:user:pass is dialled as HTTP and will not work. Write SOCKS in URL form.

• Port is required in the colon form, 1–65535; in URL form it can be omitted for a known scheme (http 80, https 443, socks 1080). No whitespace anywhere in the string.
• Up to 2048 characters — residential providers pack zone, country, city, sticky-session id and TTL into the username, so one credential can run several hundred characters. An earlier 512-character limit rejected real traffic.
• Credentials never reach logs: the value is rewritten to scheme://***:***@host:port before anything is written, and only host:port is stored.

The host is then resolved and every resolved address checked: loopback, RFC1918, link-local (including 169.254.169.254), CGNAT 100.64/10, multicast and their IPv6 equivalents are refused, as is a host that resolves to one of them or does not resolve at all. Each is 400 proxy_invalid; nothing is dispatched and nothing is billed.

proxy_unreachable is your side, not ours

Dead, overloaded or rate-limited proxies are the most common cause of failed solves we see. They get dedicated codes rather than the generic solve_failed / solve_timeout they used to hide behind, because reporting a proxy fault as a solver fault taught callers to retry us instead of fixing the proxy.

• proxy_invalid, 400 — pre-flight: malformed, bad scheme, unresolvable, or a private/reserved target. No solve attempted.
• proxy_unreachable, 502 — runtime: the solve ran and your proxy did not answer. 502, not 4xx, because the request was valid; the host it named was not.
• solve_failed, 502 — a real attempt that failed.
• key_frozen, 429 — the key tripped a per-key breaker after a burst of failed solves. The cool-off is in the message.
• proxyless_disabled, 503 — ProxyLess temporarily off. Resend with your own proxy.

A frozen key is refused before dispatch, so retries during the cool-off cost you nothing and do not extend it — but they achieve nothing either. Wait it out and fix the pool.

Retry 429, 503 and 504 with backoff; never retry a 502 without changing something first. Only a 200 carrying a token is billed, so a bad proxy costs throughput, not balance.

When a solver is the wrong answer

You control the site. Allowlist your own automation and skip all of this. A shared-secret header your middleware checks before the captcha gate, a separate staging sitekey, or a test identity that skips the challenge in staging only — faster, deterministic, free, and it keeps CI off a risk-scoring path where a score change becomes a flaky test. Paying to solve your own challenge works around a config you can change.

You are not authorized to automate the target. Then stop. No proxy configuration makes that acceptable, and nothing here is advice for getting around a control put there to keep you out. This API is for sanctioned work — QA against properties you own, authorized monitoring and accessibility checks, internal workflows — where an agent doing legitimate work hits a gate built for abusive bots. If you cannot name who authorized the access, you do not have a proxy problem.

Your IP reputation is the actual problem. A solver does not repair a burnt pool. If scores are low across sitekeys and the pattern follows your egress rather than the target, change the proxies, not the solve type.

You need v2 checkbox with an image challenge. Not supported. v2 coverage is invisible only.

Common questions