错误码

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

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

处理原则

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

全部错误码

请求格式

错误码	含义	处理办法
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 的语言规则见 请求与响应。