reCAPTCHA Error Codes from Google vs CaptchaAI: Complete Mapping

When a reCAPTCHA token fails, the error can come from three different sources: Google's siteverify API, CaptchaAI's solving API, or the target site itself. This reference maps every error code to its source, meaning, and fix.

Error Source Identification

Before debugging, identify where the error originates:

Source	Where it appears	Error format
Google siteverify	Site backend verification response	`error-codes` array (e.g., `timeout-or-duplicate`)
CaptchaAI submit	Response to `in.php` request	`ERROR_*` string (e.g., `ERROR_WRONG_USER_KEY`)
CaptchaAI poll	Response to `res.php` request	`ERROR_*` string or `CAPCHA_NOT_READY`
Target site	HTTP response or page content	Site-specific (e.g., "CAPTCHA verification failed")

Google Siteverify Error Codes

These errors appear when the target site validates your token with Google:

Error code	Meaning	Your action
`missing-input-secret`	The site's secret key was not provided	Not your problem — site misconfiguration
`invalid-input-secret`	The site's secret key is invalid	Not your problem — site misconfiguration
`missing-input-response`	Token not sent in verification request	Ensure you're injecting the token in the correct form field
`invalid-input-response`	Token is malformed or corrupted	Check for encoding issues when injecting the token
`timeout-or-duplicate`	Token expired (>2 min) or already verified	Submit token faster; never reuse tokens
`bad-request`	Malformed verification request	Not your problem — site misconfiguration

Most Common: `timeout-or-duplicate`

This is the error you'll encounter most. Two causes:

Token expired: reCAPTCHA tokens are valid for approximately 120 seconds. If your workflow takes longer between receiving the token from CaptchaAI and submitting it to the site, the token expires.

Token reused: Each token can only be verified once. If you submit the same token twice (even within the 2-minute window), the second verification fails.

Fix for both: Request a new token from CaptchaAI for each form submission. Use the token within 60 seconds.

CaptchaAI Submit Errors (in.php)

These occur when you send a task to CaptchaAI:

Error code	Meaning	Fix
`ERROR_WRONG_USER_KEY`	API key format is invalid	Check your API key — it should be a valid key from your CaptchaAI dashboard
`ERROR_KEY_DOES_NOT_EXIST`	API key not found in system	Verify the key in your CaptchaAI account
`ERROR_ZERO_BALANCE`	Insufficient account balance	Add funds to your CaptchaAI account
`ERROR_NO_SLOT_AVAILABLE`	Server is at capacity	Retry after a brief delay (1–5 seconds)
`ERROR_PAGEURL`	Missing or invalid `pageurl` parameter	Provide the full URL where the CAPTCHA appears
`ERROR_GOOGLEKEY`	Missing or invalid `googlekey` parameter	Provide the correct site key from the page
`ERROR_WRONG_CAPTCHA_ID`	Invalid captcha type or parameters	Check your `method` parameter and required fields
`ERROR_TOO_BIG_CAPTCHA_FILESIZE`	Image file exceeds size limit	Compress the image (applies to image CAPTCHAs)
`ERROR_IP_NOT_ALLOWED`	Your IP is not whitelisted	Add your IP in CaptchaAI dashboard settings
`ERROR_IP_BANNED`	Your IP is temporarily banned	Contact CaptchaAI support — excessive errors may trigger this

CaptchaAI Poll Errors (res.php)

These occur when checking task results:

Error code	Meaning	Fix
`CAPCHA_NOT_READY`	Task still being solved	Continue polling every 3–5 seconds
`ERROR_CAPTCHA_UNSOLVABLE`	CAPTCHA couldn't be solved	Retry with a new task — may be a temporary issue
`ERROR_WRONG_USER_KEY`	API key invalid	Same key issue as submit — verify your key
`ERROR_KEY_DOES_NOT_EXIST`	API key not found	Verify the key in your CaptchaAI account
`ERROR_WRONG_ID_FORMAT`	Task ID format is invalid	Use the exact ID returned by `in.php`
`ERROR_WRONG_CAPTCHA_ID`	Task ID doesn't exist	Ensure you're using the ID from the current session
`ERROR_EMPTY_ACTION`	Action parameter missing (v3)	Include `action` in your task submission

Error Flow Diagram

Submit to CaptchaAI (in.php)
├── ERROR_WRONG_USER_KEY → Fix API key
├── ERROR_ZERO_BALANCE → Add funds
├── ERROR_NO_SLOT_AVAILABLE → Retry in 1-5s
├── OK → Task ID received
│
Poll CaptchaAI (res.php)
├── CAPCHA_NOT_READY → Keep polling
├── ERROR_CAPTCHA_UNSOLVABLE → Submit new task
├── OK → Token received
│
Inject token → Submit to site
│
Site verifies with Google (siteverify)
├── timeout-or-duplicate → Token expired/reused
├── invalid-input-response → Token corrupted
├── success: true → ✓ Done

Side-by-Side Comparison

Scenario	Google error	CaptchaAI error	Which to check first
Bad API key	—	`ERROR_WRONG_USER_KEY`	CaptchaAI
No balance	—	`ERROR_ZERO_BALANCE`	CaptchaAI
Wrong site key	—	`ERROR_CAPTCHA_UNSOLVABLE`	CaptchaAI
Token too old	`timeout-or-duplicate`	—	Google (via site)
Token reused	`timeout-or-duplicate`	—	Google (via site)
Token corrupted	`invalid-input-response`	—	Google (via site)
Site key mismatch	—	`ERROR_CAPTCHA_UNSOLVABLE`	CaptchaAI
Server overloaded	—	`ERROR_NO_SLOT_AVAILABLE`	CaptchaAI
IP blocked	—	`ERROR_IP_NOT_ALLOWED`	CaptchaAI

Debugging Checklist

When a reCAPTCHA solution fails, check in this order:

CaptchaAI submit response — Did the task submit successfully?
CaptchaAI poll response — Did you get a token back?
Token injection — Is the token in the correct form field?
Token freshness — Was it used within 120 seconds?
Token uniqueness — Is this a fresh token (not reused)?
Site response — What does the target site say?

Retry Strategy by Error Type

Error	Retry?	Delay	Max retries
`ERROR_NO_SLOT_AVAILABLE`	Yes	1–5s	5
`ERROR_CAPTCHA_UNSOLVABLE`	Yes (new task)	0s	3
`CAPCHA_NOT_READY`	Yes (continue poll)	3–5s	60
`timeout-or-duplicate`	Yes (new token)	0s	3
`ERROR_ZERO_BALANCE`	No	—	—
`ERROR_WRONG_USER_KEY`	No	—	—
`ERROR_IP_BANNED`	No	—	—

FAQ

How do I know if the error is from Google or CaptchaAI?

CaptchaAI errors start with ERROR_ or return CAPCHA_NOT_READY. Google's siteverify errors are lowercase with hyphens (e.g., timeout-or-duplicate). If you got a token from CaptchaAI but the site rejects it, the issue is between the site and Google.

Why do I get `timeout-or-duplicate` even when I submit quickly?

The token's 120-second timer starts when CaptchaAI generates it, not when you receive it. If polling took 30 seconds and your workflow adds another 90+ seconds before submission, the token expires. Optimize your submission pipeline to use tokens within 60 seconds.

Should I report `ERROR_CAPTCHA_UNSOLVABLE` to CaptchaAI?

Occasional unsolvable errors are normal — some challenges are genuinely difficult. If the rate exceeds 10%, check that you're sending the correct site key and page URL. Contact CaptchaAI support if the issue persists.