Skip to main content

Error descriptions

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.

Quick handling rules​

  • 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.

Index​

Submit (in.php) errors​

INVALID KEY ERROR_WRONG_USER_KEY​

key value has incorrect format (must be 32 characters).
Fix: verify API key format.

KEY DOES NOT EXIST ERROR_KEY_DOES_NOT_EXIST​

Provided key does not exist.
Fix: check you’re using the key from your dashboard.

NO FUNDS / THREADS ERROR_ZERO_BALANCE​

Insufficient balance/threads to accept the task.
Fix: top up or reduce concurrency and retry.

PAGE URL MISSING ERROR_PAGEURL​

pageurl is required for certain captcha types.
Fix: include a valid pageurl.

BIG IMAGE SIZE ERROR_TOO_BIG_CAPTCHA_FILESIZE​

Uploaded image exceeds the allowed size.
Fix: compress or resize the image and resubmit.

ZERO IMAGE SIZE ERROR_ZERO_CAPTCHA_FILESIZE​

Image payload is too small (< 100 bytes).
Fix: ensure you send a real image/base64 data.

WRONG FILE EXTENSION ERROR_WRONG_FILE_EXTENSION​

Unsupported image extension. Allowed: jpg,jpeg,png,gif.
Fix: use a supported type.

IMAGE TYPE NOT SUPPORTED ERROR_IMAGE_TYPE_NOT_SUPPORTED​

Server cannot recognize the image type.
Fix: convert to a standard format (PNG/JPG).

UPLOAD ERROR ERROR_UPLOAD​

Server can’t read the file or base64 payload.
Fix: fix multipart/base64 encoding.

IP BANNED IP_BANNED​

IP banned after repeated bad authorization.
Fix: wait ~5 minutes and send correct credentials.

BAD TOKEN OR PAGEURL (reCAPTCHA v2) ERROR_BAD_TOKEN_OR_PAGEURL​

Invalid googlekey + pageurl pair (often due to iframes/other domains).
Fix: extract the correct sitekey and page URL from the target page.

GOOGLEKEY MISSING/MALFORMED ERROR_GOOGLEKEY/ERROR_WRONG_GOOGLEKEY​

googlekey value blank/malformed or parameter missing.
Fix: pass the correct sitekey.

BAD PARAMETERS ERROR_BAD_PARAMETERS​

Required parameters missing or wrong types.
Fix: validate request schema.

BAD PROXY ERROR_BAD_PROXY​

Submitted proxy is marked BAD.
Fix: change to a known-good proxy.

SERVER ERROR ERROR_SERVER_ERROR/ERROR_INTERNAL_SERVER_ERROR​

Transient server-side error.
Fix: retry after ~10s with backoff.

Result (res.php) errors​

NOT READY YET CAPCHA_NOT_READY​

Result isn’t ready.
Fix: poll every ~5s using action=get&id=<ID>.

CAPTCHA UNSOLVABLE ERROR_CAPTCHA_UNSOLVABLE​

Service failed to solve after several attempts / unsupported.
Fix: verify captcha type and parameters; consider resubmitting.

INVALID KEY ERROR_WRONG_USER_KEY​

key format invalid (must be 32 characters).
Fix: verify the key format.

KEY DOES NOT EXIST ERROR_KEY_DOES_NOT_EXIST​

Provided key does not exist.
Fix: use a valid dashboard key.

WRONG ID FORMAT ERROR_WRONG_ID_FORMAT​

Captcha ID must be numeric.
Fix: send digits-only ID.

WRONG CAPTCHA ID ERROR_WRONG_CAPTCHA_ID​

Captcha ID is incorrect.
Fix: verify you’re polling the ID returned by submission.

EMPTY ACTION ERROR_EMPTY_ACTION​

Missing/empty action parameter.
Fix: set action=get, getbalance, etc.

PROXY CONNECTION FAILED ERROR_PROXY_CONNECTION_FAILED​

Couldn’t load captcha through your proxy; proxy is marked BAD temporarily.
Fix: switch to a healthy proxy.

INTERNAL SERVER ERROR ERROR_INTERNAL_SERVER_ERROR​

Transient error while processing the captcha.
Fix: retry after ~10s.

Best practices​

  • Log the full error code and request context (params, captcha type, ID).
  • Use a fixed 5s poll for <span class="badge note">CAPCHA_NOT_READY</span> and exponential backoff for 5xx/transient errors.
  • Validate inputs (API key, required params, image size/type) before calling the API.
  • Keep task IDs and retries bounded to avoid unnecessary spend and rate limits.