# 错误码

> YesCaptcha API 全部错误码的含义和处理办法：请求格式、账户余额、并发与暂停、任务结果、网站参数、图片、代理、服务端。返回错误的请求不扣点。

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

接口出错时返回 `errorId: 1`，`errorCode` 是错误码，`errorDescription` 是文字说明。返回错误的请求不扣点：创建任务时就出错的不扣，创建后识别失败、超时的自动退点。程序里按 `errorCode` 判断，不要按 `errorDescription` 的文字判断。

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

## 处理原则

1.  **参数类错误**（请求格式、密钥、任务类型、网站参数、图片）重发也不会变，要先改请求。
2.  **识别失败和超时**（`ERROR_CAPTCHA_UNSOLVABLE`、`ERROR_TASK_TIMEOUT`）可以重新创建任务。
3.  出错后**停止轮询**这个 `taskId`，不要原样高频重发。
4.  标“计入自动暂停”的错误，同一个 `clientKey` 一分钟内出现 100 次会被暂停创建任务 5 分钟；标“缓存”的错误不计入，但缓存期内同样的请求直接返回原错误。详见 [并发限制与自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits/)。

## 全部错误码

### 请求格式

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 缺少必填字段（比如 `clientKey`，或这个任务类型要求的 `websiteURL`、`websiteKey`），或者请求体不是 JSON | 对照任务类型页的参数表补全字段；用 `POST` 发送 JSON，并带上 `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (计入自动暂停) | 请求体不是合法的 JSON | 用 JSON 库生成请求体，不要手拼字符串；JSON 里不能有 `//` 注释 |
| `ERROR_TASK_ABSENT` (计入自动暂停) | 调用 `createTask` 时没有 `task` 字段 | 把任务参数放进 `task` 对象。Python requests 要用 `json=data`，不要用 `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (计入自动暂停) | `task.type` 拼写错误，或者这个类型已经下线 | 从"任务类型与价格"复制类型名，注意大小写 |
| `ERROR_PAGE_NOT_FOUND` | 请求的路径不存在 | 检查接口地址，例如 `https://api.yescaptcha.com/createTask`，方法名区分大小写 |
| `ERROR_BAD_REQUEST` | 请求无法处理，常见于请求方法不对（用了 GET）或参数内容不合法 | 用 `POST` 发送 JSON；检查参数的类型和取值 |

### 账户与余额

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (计入自动暂停) | `clientKey` 不存在：复制时多了或少了字符，或者密钥已经在后台重置 | 到 yescaptcha.com 后台重新复制密钥。不要带空格和换行 |
| `ERROR_ZERO_BALANCE` | 余额不足。余额必须大于 10 点才能创建任务 | 充值后重试。可以用 `getBalance` 查余额 |

### 并发与暂停

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (部分情况计入自动暂停) | 这个账号这种任务同时处理中的请求超过了并发上限，响应里的 `limit` 是当前上限。这个请求没有被处理，不扣点 | 等已发出的请求返回后再发新的，或者等 1 到 2 秒再试；在程序里限制同时等待结果的请求数 |
| `ERROR_IP_BLOCKED_5MIN` | 这个 `clientKey` 短时间内错误太多，被自动暂停创建任务。响应里的 `retryAfter` 是剩余秒数，`blockReason` 是触发暂停的错误码 | 按 `blockReason` 修正请求，等 `retryAfter` 秒后自动恢复；暂停期间继续发送不会延长时间 |
| `ERROR_NO_SLOT_AVAILABLE` | 识别服务暂时忙不过来 | 等几秒后重试 |

### 任务与结果

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (计入自动暂停) | `taskId` 不存在、已过期（结果保留约 10 分钟），或者不是这个 `clientKey` 创建的；也可能是在另一个节点创建的 | 停止轮询这个任务。用创建任务的同一个节点、同一个 `clientKey` 查询 |
| `ERROR_TASK_TIMEOUT` | 任务在规定时间内（一般 110 秒）没有完成，已自动退点 | 重新创建任务；持续超时可以换一个同类的任务类型 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 这次没有识别出来，已自动退点。不计入自动暂停 | 重新创建任务。持续失败时检查 `websiteURL`、`websiteKey` 等参数，或者换一个同类的任务类型 |
| `ERROR_SETTLEMENT_FAILED` (计入自动暂停) | 结算时余额不足，结果没有返回 | 充值后重新创建任务 |
| `ERROR_NO_SUCH_CAPCHA_ID` | 任务已失效 | 停止轮询这个任务，重新创建 |
| `ERROR_RECAPTCHA_TIMEOUT` | 识别验证码超时，已自动退点 | 重新创建任务 |

### 目标网站参数

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (缓存，不计入暂停) | `websiteKey` 无效 | 重新在网页里找 sitekey（见"查找参数"教程）。同样的请求在缓存期内会直接返回这个错误，响应带 `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (缓存，不计入暂停) | `websiteURL` 的域名和 `websiteKey` 对不上 | `websiteURL` 填出现验证码的那个网页的地址 |
| `ERROR_INVALID_KEY_TYPE` (缓存，不计入暂停) | sitekey 属于另一种验证码，比如把 v3 的 key 用在了 v2 的任务类型上 | 先判断验证码类型（见"判断验证码类型"），再选对应的任务类型；v2 隐形版要传 `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (缓存，不计入暂停) | 这个网站暂时不支持 | 换一个同类的任务类型试试，或者联系客服 |
| `ERROR_HIGH_DEMAND_DOMAIN` (计入自动暂停) | 这个网站暂时不支持 | 停止发送这个网站的任务，联系客服确认 |
| `ERROR_FAILED_LOADING_WIDGET` | 用你给的参数加载不出验证码 | 检查 `websiteURL`、`websiteKey`；自带代理的类型检查代理能否访问目标网站 |

### 图片

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (计入自动暂停) | 图片为空或太小 | 检查 Base64 内容是否完整，不要带 `data:image/...;base64,` 前缀 |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (计入自动暂停) | 图片太大 | 压缩或缩小图片后再发；整个请求体不能超过 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (计入自动暂停) | 图片格式不支持，或者不是这个任务类型能处理的图片。出现 1 次就暂停 30 分钟 | 用 JPG 或 PNG；确认图片和任务类型对应，例如 reCAPTCHA 图像识别的图片要缩放到 100x100、300x300 或 450x450 |
| `ERROR_ILLEGAL_IMAGE` (计入自动暂停) | 图片尺寸不符合这个任务类型的要求 | 按任务类型页的说明调整图片尺寸 |
| `ERROR_PARSE_IMAGE_FAIL` | 图片无法解析，常见于 Base64 不完整或带了前缀 | 检查 Base64 编码；去掉 `data:` 前缀和换行 |
| `ERROR_UNKNOWN_QUESTION` | `question` 填错了，或者这道题目暂时还不支持 | 对照任务类型页的题目列表检查；确实不支持的题目可以联系客服，新题目一般 3 个工作日内支持 |
| `ERROR_UNKNOW_450x450_QUESTION` | 这道题目暂时不支持 4x4（450x450）的图片 | 在网页上刷新换一题 |

### 代理

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | 代理拒绝连接 | 检查代理地址、端口和协议；确认代理允许外部访问（不能是 127.0.0.1 这类本机地址） |
| `ERROR_PROXY_CONNECT_TIMEOUT` | 连接代理超时 | 换一个更稳定的代理 |
| `ERROR_PROXY_READ_TIMEOUT` | 通过代理读取数据超时 | 换一个更快的代理 |
| `ERROR_PROXY_BANNED` | 代理不可用，或者代理的 IP 被目标网站封了 | 换一个代理 |
| `ERROR_PROXY_INCORRECT` | 代理参数的格式不对 | 检查 `proxyType`、`proxyAddress`、`proxyPort`（或 `proxy` 字符串）的格式 |
| `ERROR_PROXY_TRANSPARENT` | 代理是透明代理，会暴露真实 IP | 换成匿名（高匿）代理 |
| `ERROR_PROXY_NOT_AUTHORISED` | 代理的用户名或密码不对 | 检查 `proxyLogin`、`proxyPassword` |
| `ERROR_PROXY_TLS_ERROR` | 和代理的 TLS 握手失败，常见于 `proxyType` 填错（比如 http 代理填了 https） | 核对代理协议 |
| `ERROR_PROXY_CONNECTION_FAILED` | 连不上代理服务器 | 检查代理地址和端口，确认代理正常工作 |

### 服务端

| 错误码 | 含义 | 处理办法 |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | 服务暂时不可用（错误码的拼写就是 `UNAVALIABLE`） | 稍后重试；持续出现请联系客服 |
| `ERROR_INTERNAL_SERVER_ERROR` | 服务端出错 | 稍后重试；持续出现请联系客服并提供 `taskId` |
| `ERROR_UNKNOWN` | 未归类的错误 | 稍后重试；持续出现请联系客服并提供 `taskId` |

## 附加字段

部分错误的响应带有额外字段：

| 字段 | 出现在 | 说明 |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`、缓存的错误 | 还要等多少秒 |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | 触发暂停的错误码 |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | 触发暂停的那类请求的类型、网址、sitekey，方便定位 |
| `cached` | 缓存的错误 | 为 `true` 表示这是缓存的结果，没有实际识别 |
| `badRequest` | 缓存的错误 | 命中缓存的参数 |
| `limit` | `ERROR_THREADS_MAXIMUM` | 你当前的并发上限 |

`errorDescription` 的语言规则见 [请求与响应](https://docs.yescaptcha.com/zh/api/overview/#%E6%8F%90%E7%A4%BA%E6%96%87%E5%AD%97%E7%9A%84%E8%AF%AD%E8%A8%80)。