This page lists all CaptchaAI API error codes from legacy endpoints in.php (submit) and res.php (result) and provides recommended fixes.
Use json=1 to receive JSON responses ({"status":0,"request":"ERROR_CODE"}); otherwise errors are returned as plain text like ERROR_CODE.
CAPCHA_NOT_READY→ poll every ~5 seconds.- Transient server errors → retry after ~10 seconds (consider exponential backoff).
- Parameter/format errors → fix the request before retrying.
key value has incorrect format (must be 32 characters).
Fix: verify API key format.
Provided key does not exist.
This could be due to:
1. Wrong API Key
- Fix: Make sure you are using the API key from your dashboard, or generate a new one.
2. Your Account Has No Threads
- Fix: Start a trial or subscribe to a plan.
You don't have free threads to accept a new task.
Fix: top up or reduce concurrency and retry.
pageurl is required for certain CAPTCHA types.
Fix: include a valid pageurl.
Uploaded image exceeds the allowed size (1024 KB Max).
Fix: compress or resize the image and resubmit.
Image payload is too small (< 1 KB).
Fix: ensure you send a real image/base64 data.
Unsupported image extension. Allowed: jpg,jpeg,png,gif.
Fix: use a supported type.
Server cannot recognize the image type.
Fix: convert to a standard format (PNG/JPG).
Server can’t read the file or base64 payload.
Fix: fix base64 encoding.
Invalid googlekey + pageurl pair (often due to iframes/other domains).
Fix: extract the correct sitekey and page URL from the target page.
googlekey value blank/malformed or parameter missing.
Fix: pass the correct sitekey.
Required parameters missing or wrong types.
Fix: validate request schema.
Submitted proxy is marked BAD.
Fix: change to a known-good proxy.
Transient server-side error.
Fix: retry after ~10s with backoff.
Transient server-side error.
Fix: retry after ~10s with backoff.
Result isn’t ready.
Fix: Poll the result endpoint every ~5 seconds. See the Solving Guides for the recommended polling speed for each CAPTCHA type.
Service failed to solve after several attempts / unsupported.
Fix: verify CAPTCHA type and parameters; consider resubmitting.
key format invalid (must be 32 characters).
Fix: verify the key format.
Provided key does not exist.
Fix: use a valid dashboard key.
Captcha ID must be numeric.
Fix: send digits-only ID.
Captcha ID is incorrect.
Fix: verify you’re polling the ID returned by submission.
Missing/empty action parameter.
Fix: set action=get, getbalance, etc.
Couldn’t load CAPTCHA through your proxy; proxy is marked BAD temporarily.
Fix: switch to a healthy proxy.
Transient error while processing the CAPTCHA.
Fix: retry after ~10s.
- Log the full error code and request context (params, CAPTCHA type, ID).
- Use the recommended polling interval for each CAPTCHA type when handling
CAPCHA_NOT_READY. - Validate inputs (API key, required params, image size/type) before calling the API.
- Keep Task IDs and retries bounded to avoid unnecessary thread acquisition.