Error codes

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.

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

errorDescription is in Chinese for most codes; see 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.

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