style

.badge{display:inline-block;padding:.14rem .5rem;border-radius:.45rem;
font-size:.75rem;line-height:1;border:1px solid #444;background:#1f2430;color:#cbd5e1}
.badge.err{border-color:#a54444;background:#2a1717;color:#f2b8b8}
.badge.note{border-color:#3b82f6}
kbd{background:#1f2937;border:1px solid #374151;border-radius:4px;padding:0 .35rem}
.code{font-family:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace}

# 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](#submit--inphp--errors)
- [Result (`res.php`) errors](#result--resphp--errors)
- [Best practices](#best-practices)


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

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.


### NO AVAILABLE THREADS ERROR_ZERO_BALANCE

You don't have free threads to accept a new 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 (1024 KB Max).
**Fix:** compress or resize the image and resubmit.

### ZERO IMAGE SIZE ERROR_ZERO_CAPTCHA_FILESIZE

Image payload is too small (< 1 KB).
**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 base64 encoding.

### BAD TOKEN OR PAGEURL (reCAPTCHA) 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

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

### OCR 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 the result endpoint every ~5 seconds. See the [Solving Guides](/guides/tasks/normal-captcha) for the recommended polling speed for each CAPTCHA type.

### 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 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 ID**s and retries bounded to avoid unnecessary thread acquisition.