CAPTCHA Solver Troubleshooting Guide

CAPTCHA solver integrations fail in predictable, repeatable ways. Most issues fall into five categories: the solve request times out, the solve succeeds but the token is rejected by the target site, the solver returns an API error code, success rates are lower than expected, or a Cloudflare challenge never clears. This guide is the index — use the diagnostic table below to find the right article for your specific problem, or read the full section for root cause analysis and fixes.

Quick Diagnostic Table

Symptom	Most Likely Cause	Go To
Request hangs or raises `TimeoutError`	Solver queue backed up; polling interval too short	Timeout Errors
`ERROR_CAPTCHA_UNSOLVABLE` returned	Flagged IP; wrong parameters; hard challenge tier	Low Success Rate
`ERROR_WRONG_USER_KEY` or `ERROR_KEY_DOES_NOT_EXIST`	Wrong API key; account suspended	API Error Codes
`ERROR_ZERO_BALANCE`	Account credits exhausted	API Error Codes
Solver returns a token but the site rejects it	Token expired; wrong site key; Enterprise mismatch	Token Invalid/Expired
Cloudflare page keeps showing after solve attempt	Turnstile token vs challenge page confusion; wrong task type	Cloudflare Not Solving
Success rate < 80% consistently	IP reputation; solver not suited for challenge type	Low Success Rate
Works in development, fails in production	Production environment fingerprint differs; proxy issue	Low Success Rate
Token works once but pipeline keeps re-triggering	CAPTCHA persisting after solve; token not being injected properly	Token Invalid/Expired

Category 1 — Timeout Errors

Timeout errors occur when the solver's API does not return a result within your polling window. There are three different timeout points:

Submission timeout — The HTTP POST to /in.php or the task creation endpoint itself hangs. Usually a network or endpoint availability issue.

Queue timeout — The task is accepted (you have a task ID) but the solver never returns a result. Most common when: (a) the solver's worker pool is saturated, (b) the task is malformed and silently fails, or (c) you stop polling too early.

Your application timeout — Your polling loop exits before the solver finishes. FunCaptcha and GeeTest can take 30–60 seconds; polling 5–10 times with 5-second gaps is not enough.

Quick checks: 1. Confirm the task ID was received (status 1 on submission) 2. Increase poll attempts to at least 30 × 5 seconds (150 seconds total) 3. Start polling at the right delay: 15s for FunCaptcha/GeeTest, 5s for image CAPTCHAs, 8s for reCAPTCHA v3

→ See Fixing CAPTCHA Solver Timeout Errors for the complete fix guide.

Category 2 — Low Success Rates

A success rate below 80% consistently indicates a systemic problem, not random solver failures. Causes fall into three groups:

IP reputation issues — The IP address used for the page request (not the solver API call) is flagged. Behavioral CAPTCHA systems (reCAPTCHA v3, FunCaptcha, GeeTest v4) factor in the originating IP's reputation when determining challenge difficulty. A flagged datacenter IP consistently receives harder challenges that lower-tier solver workers fail on.

Wrong solver for the challenge type — Not every solver performs equally on every CAPTCHA type. Using a solver with limited FunCaptcha support for a FunCaptcha-heavy target will produce systematically low results. Check the CaptchaRank leaderboard for type-specific rankings.

Missing or wrong parameters — Many solvers have optional parameters that significantly affect success rate. For reCAPTCHA v3, not setting min_score means the solver may return a low-scoring token the site rejects. For GeeTest, passing a stale challenge value guarantees failure.

Quick checks: 1. Is the success rate low on all sites, or just one? (One site = likely IP or site-specific enforcement; all sites = solver issue) 2. Are you passing all required type-specific parameters? 3. What is CaptchaAI's baseline on the same CAPTCHA type? (CaptchaAI achieves ~96–98% on most types per CaptchaRank benchmark — if you're well below that, consider a solver switch)

→ See Why Is My CAPTCHA Solver Success Rate Low? for the complete diagnosis.

Category 3 — API Error Codes

Solver APIs (2Captcha-format and JSON-format) return machine-readable error codes. The most common ones and what they mean:

Error Code	Meaning	Fix
`ERROR_WRONG_USER_KEY`	API key format invalid	Check key length and format in dashboard
`ERROR_KEY_DOES_NOT_EXIST`	Key not found in DB	Verify key; check account status
`ERROR_ZERO_BALANCE`	No credits	Top up account
`ERROR_PAGEURL`	`pageurl` missing or malformed	Ensure full URL including `https://`
`ERROR_CAPTCHA_UNSOLVABLE`	Solver could not complete	Retry; switch solver; check IP
`ERROR_BAD_PARAMETERS`	Required field missing	Check solver docs for task type
`ERROR_WRONG_GOOGLEKEY`	reCAPTCHA site key invalid	Re-extract from page at runtime
`ERROR_IMAGE_TYPE_NOT_SUPPORTED`	Image format not accepted	Convert to JPEG/PNG before base64 encoding

→ See CAPTCHA Solver API Error Codes Explained for the full code reference with recovery patterns.

Category 4 — Token Rejected by Target Site

Receiving a valid-looking token from the solver but having it rejected by the target site is one of the most frustrating failure modes. Root causes:

Token expired — reCAPTCHA, hCaptcha, and Turnstile tokens expire in 2 minutes; FunCaptcha tokens in 2–3 minutes. If more than 2 minutes pass between the solve and the form submission, the token is invalid. The fix: solve immediately before submission, not at session start.

Site key mismatch — The site key used for the solver request must exactly match the key on the page. Some sites have different keys for staging vs. production. Always extract the site key dynamically from the page HTML.

Enterprise vs. standard token — If a site uses reCAPTCHA Enterprise (enterprise.js) but you submitted a standard v2 task, the token type won't pass Enterprise server verification. Use the Enterprise task type.

Token injected into wrong field — Different CAPTCHA types use different hidden field names: g-recaptcha-response (reCAPTCHA), h-captcha-response (hCaptcha), cf-turnstile-response (Turnstile). Injecting into the wrong field is a silent failure.

→ See reCAPTCHA Token Invalid or Expired: How to Fix for full treatment.

Category 5 — Cloudflare Challenges Not Clearing

Cloudflare-protected pages have two distinct protection mechanisms that require different solving approaches. Confusing them is the most common source of Cloudflare-related failures:

Turnstile — A widget embedded in a form. Solved with a standard task API call; returns a cf-turnstile-response token injected into the form.
Challenge pages — A full-page interstitial ("Checking your browser…"). Solved with a browser session that returns cf_clearance cookies.

Attempting to solve a Challenge page with a Turnstile token solver will always fail. These are different products requiring different solver capabilities.

→ See Cloudflare Challenge Not Solving: Causes and Fixes for the complete diagnosis.

Choosing a More Reliable Solver

If you've worked through the specific issue articles and your success rate remains low, the problem may be solver-level. CaptchaAI consistently achieves the highest benchmark success rates across CAPTCHA types in CaptchaRank's live monitoring — particularly on reCAPTCHA v2/v3, Turnstile, and FunCaptcha. If you're seeing persistent failures on a 2Captcha-compatible API, switching the endpoint to https://ocr.captchaai.com (keeping all other parameters) is a zero-code-change test.

Compare all solvers by success rate, speed, and pricing on the CaptchaRank leaderboard.