CaptchaTroubleshooting
Diagnose and fix the most common integration problems — auth, uploads, rate limits, and solver-specific issues.
Error Reference
Native endpoints (/api/*.php) return JSON errors; the 2Captcha-compatible pair (in.php/res.php) returns text error strings.
JSON API Errors (native endpoints)
| HTTP | Error Message | Cause & Fix |
|---|---|---|
400 |
Invalid API key or account inactive | Wrong key or disabled account — copy the key from your dashboard; send it in the Authorization: Bearer or X-API-Key header |
403 |
Insufficient credits | Balance is empty — top up; new accounts start with $0.50 free |
400 |
No file uploaded | Missing multipart file field — the field name must be captcha |
400 |
Invalid file type | Unsupported format — upload JPG, PNG, or GIF (WebP is converted server-side) |
400 |
File size exceeds 5MB | Image too large — resize or compress before upload |
405 |
Method not allowed | GET used on a POST-only endpoint — switch to POST |
429 |
Rate limit exceeded | Above your plan's per-minute allowance — wait 1 minute, then retry; see Rate Limits |
Legacy Text Errors (in.php / res.php)
| Error String | Meaning | Fix |
|---|---|---|
KEY_DOES_NOT_EXIST |
API key not recognized | Check the key parameter against your dashboard key |
ZERO_BALANCE |
No credit remaining | Top up your balance |
UPLOAD_FAILURE |
Image could not be received/decoded | Re-send a valid JPG/PNG/GIF image |
CAPTCHA_UNSOLVABLE |
Pipeline could not solve this image | Send a clearer capture; not billed |
NO_SUCH_CAPCHA_ID |
res.php?action=get with an unknown task ID |
Use the exact ID returned by in.php; IDs come only from the xCaptcha pipeline |
Common Symptoms
"I get 400 Invalid API key on every request"
- Confirm the key is sent as
Authorization: Bearer KEY,X-API-Key: KEY, or POST fieldapi_key(native) /keyparameter (legacy pair). - Watch for trailing whitespace or quotes when copying from the dashboard.
- Check the account is active and the key has not been rotated.
"My request times out"
- Compare your client timeout against the measured p95 in Task Lifecycle: 5s is enough for most solvers; Amazon WAF needs 30s.
- On 429s, back off 60 seconds instead of retrying immediately.
"res.php says NO_SUCH_CAPCHA_ID"
- The legacy pair only tracks IDs created by
in.phpon this account — IDs from other services or other endpoints will not resolve. - Verify the
idparameter matches the task ID from thein.phpresponse exactly.
"Accuracy is lower than the benchmarks"
- OCR / text: send the captcha as a single line; upscale small images ~2× before upload; avoid re-compressed JPEGs.
- GeeTest: submit the challenge image at natural pixel size (no CSS-scaled screenshots); slider trajectories should run 600–900ms; always use a fresh challenge image.
- Amazon WAF: capture at full resolution and set client timeout ≥ 30s (p95 is 14s).
- Compare against the measured baselines at /benchmarks before tuning further.
"Am I being double-charged on retries?"
- 4xx rejections and failed solves are never billed.
- Amazon WAF retries submitted with
is_retry=trueare not billed twice. - Store successful answers instead of re-solving the same image.
Still Stuck?
Email [email protected] with the endpoint, HTTP status, full error message, and a sample image. Typical response time is under 24 hours.
Related: Error Handling · Task Lifecycle · Rate Limits