# Error codes

> Every YesCaptcha API error code with its meaning and what to do, grouped by request format, account and balance, concurrency and pauses, tasks, site parameters, images, proxies and server. Requests that return an error are not charged.

Source: https://docs.yescaptcha.com/en/api/errors/ · Last verified: 2026-10-15

On failure the API returns `errorId: 1`, an error code in `errorCode` and a text description in `errorDescription`. Requests that return an error are not charged: errors at creation are never charged, and tasks that fail or time out after creation are refunded automatically. Branch on `errorCode` in your code, not on the wording of `errorDescription`.

```json
{ "errorId": 1, "errorCode": "ERROR_ZERO_BALANCE", "errorDescription": "帐户余额不足" }
```

`errorDescription` is in Chinese for most codes; see [Message language](https://docs.yescaptcha.com/en/api/overview/#message-language).

## How to handle errors

1.  **Parameter errors** (request format, key, task type, site parameters, images) won’t change if you resend; fix the request first.
2.  **Solving failures and timeouts** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) can be retried by creating a new task.
3.  After an error, **stop polling** that `taskId`. Don’t resend the same request at a high rate.
4.  Errors marked “Counts toward pause” pause task creation for 5 minutes once one `clientKey` gets 100 of them within a minute. Errors marked “Cached” don’t count, but identical requests return the same error while cached. See [Rate limits](https://docs.yescaptcha.com/en/api/rate-limits/).

## All error codes

### Request format

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | A required field is missing (such as `clientKey`, or `websiteURL` / `websiteKey` for the task type), or the body is not JSON | Add the missing fields listed on the task type page, and send JSON with `POST` and `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Counts toward pause) | The request body is not valid JSON | Build the body with a JSON library instead of string concatenation; JSON must not contain `//` comments |
| `ERROR_TASK_ABSENT` (Counts toward pause) | The `task` field is missing in a `createTask` call | Put the task parameters in a `task` object. With Python requests use `json=data`, not `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Counts toward pause) | `task.type` is misspelled or the type has been retired | Copy the type name from "Task types and pricing"; names are case-sensitive |
| `ERROR_PAGE_NOT_FOUND` | The requested path does not exist | Check the endpoint URL, e.g. `https://api.yescaptcha.com/createTask`; method names are case-sensitive |
| `ERROR_BAD_REQUEST` | The request cannot be processed, usually because of a wrong HTTP method (GET instead of POST) or invalid parameter values | Send JSON with `POST`, and check the parameter types and values |

### Account and balance

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Counts toward pause) | The `clientKey` does not exist: characters were added or lost when copying, or the key was reset in the dashboard | Copy the key again from the yescaptcha.com dashboard, without spaces or line breaks |
| `ERROR_ZERO_BALANCE` | Insufficient balance. The balance must be above 10 points to create a task | Top up and retry. Use `getBalance` to check the balance |

### Concurrency and pauses

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Sometimes counts toward pause) | Too many tasks of this type are in progress for the account. `limit` in the response is the current limit. The request was not processed and not charged | Wait for in-flight requests to return, or wait 1–2 seconds and retry; cap the number of requests waiting at the same time |
| `ERROR_IP_BLOCKED_5MIN` | This `clientKey` produced too many errors in a short time and was automatically paused. `retryAfter` is the remaining seconds and `blockReason` is the error that caused it | Fix the request according to `blockReason` and wait `retryAfter` seconds; sending during the pause does not extend it |
| `ERROR_NO_SLOT_AVAILABLE` | The solving service is temporarily overloaded | Retry after a few seconds |

### Tasks and results

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Counts toward pause) | The `taskId` does not exist, has expired (results are kept for about 10 minutes), belongs to another `clientKey`, or was created on the other endpoint | Stop polling this task. Query with the same endpoint and `clientKey` that created it |
| `ERROR_TASK_TIMEOUT` | The task did not finish in time (usually 110 seconds); the points were refunded automatically | Create a new task; if it keeps timing out, try another task type for the same captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | The captcha could not be solved this time; the points were refunded. This does not count toward the automatic pause | Create a new task. If it keeps failing, check `websiteURL`, `websiteKey` and other parameters, or try another task type for the same captcha |
| `ERROR_SETTLEMENT_FAILED` (Counts toward pause) | The balance was insufficient at settlement, so no result was returned | Top up and create a new task |
| `ERROR_NO_SUCH_CAPCHA_ID` | The task is no longer valid | Stop polling this task and create a new one |
| `ERROR_RECAPTCHA_TIMEOUT` | Solving the captcha timed out; the points were refunded | Create a new task |

### Target site parameters

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Cached, no pause) | The `websiteKey` is invalid | Find the sitekey on the page again (see the guides on finding parameters). Identical requests return this error directly during the cache period, with `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Cached, no pause) | The domain of `websiteURL` does not match the `websiteKey` | Set `websiteURL` to the page that shows the captcha |
| `ERROR_INVALID_KEY_TYPE` (Cached, no pause) | The sitekey belongs to a different captcha, e.g. a v3 key used with a v2 task type | Identify the captcha first (see "Identify the captcha type") and choose the matching task type; for invisible v2 set `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Cached, no pause) | This site is not supported | Try another task type for the same captcha, or contact support |
| `ERROR_HIGH_DEMAND_DOMAIN` (Counts toward pause) | This site is not supported | Stop sending tasks for this site and contact support |
| `ERROR_FAILED_LOADING_WIDGET` | The captcha could not be loaded with the given parameters | Check `websiteURL` and `websiteKey`; for task types with your own proxy, check that the proxy can reach the site |

### Images

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Counts toward pause) | The image is empty or too small | Check that the Base64 data is complete and has no `data:image/...;base64,` prefix |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Counts toward pause) | The image is too large | Compress or resize the image; the whole request body must stay under 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Counts toward pause) | The image format is not supported, or the image is not one this task type can handle. A single occurrence pauses the key for 30 minutes | Use JPG or PNG and make sure the image matches the task type, e.g. reCAPTCHA image recognition needs 100x100, 300x300 or 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Counts toward pause) | The image size does not meet the requirements of this task type | Resize the image as described on the task type page |
| `ERROR_PARSE_IMAGE_FAIL` | The image could not be decoded, often because the Base64 is truncated or has a prefix | Check the Base64 encoding and remove the `data:` prefix and line breaks |
| `ERROR_UNKNOWN_QUESTION` | The `question` is wrong, or this question is not supported yet | Check it against the question list on the task type page. For unsupported questions contact support; new questions are usually supported within 3 business days |
| `ERROR_UNKNOW_450x450_QUESTION` | This question is not supported for 4x4 (450x450) images yet | Reload the challenge on the page to get another question |

### Proxies

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | The proxy refused the connection | Check the proxy address, port and protocol, and make sure it accepts external connections (not a local address such as 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Connecting to the proxy timed out | Use a more reliable proxy |
| `ERROR_PROXY_READ_TIMEOUT` | Reading through the proxy timed out | Use a faster proxy |
| `ERROR_PROXY_BANNED` | The proxy is unavailable, or its IP is blocked by the target site | Use another proxy |
| `ERROR_PROXY_INCORRECT` | The proxy parameters are malformed | Check the format of `proxyType`, `proxyAddress`, `proxyPort` (or the `proxy` string) |
| `ERROR_PROXY_TRANSPARENT` | The proxy is transparent and exposes the real IP | Use an anonymous (elite) proxy |
| `ERROR_PROXY_NOT_AUTHORISED` | The proxy username or password is wrong | Check `proxyLogin` and `proxyPassword` |
| `ERROR_PROXY_TLS_ERROR` | The TLS handshake with the proxy failed, often because `proxyType` is wrong (e.g. https set for an http proxy) | Check the proxy protocol |
| `ERROR_PROXY_CONNECTION_FAILED` | Could not connect to the proxy server | Check the proxy address and port and make sure the proxy is working |

### Server

| Error code | Meaning | What to do |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | The service is temporarily unavailable (the code is spelled `UNAVALIABLE`) | Retry later; contact support if it persists |
| `ERROR_INTERNAL_SERVER_ERROR` | An internal server error occurred | Retry later; if it persists, contact support with the `taskId` |
| `ERROR_UNKNOWN` | An unclassified error | Retry later; if it persists, contact support with the `taskId` |

## Extra fields

Some error responses carry extra fields:

| Field | Returned with | Description |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, cached errors | Seconds left to wait |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | The error code that caused the pause |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Type, URL and sitekey of the requests that caused the pause |
| `cached` | Cached errors | `true` means this is a cached answer; nothing was solved |
| `badRequest` | Cached errors | The parameters that hit the cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Your current concurrency limit |