Error reference

When a call fails

Every solver answers with the same error shape. This page lists every errorCode the task API can return for Cloudflare Turnstile, reCAPTCHA v3 and reCAPTCHA v2: what it means, and whether to retry.

How errors arrive

These codes come from the task API: getToken, createTask and getTaskResult under /turnstile and /recaptcha.

JSON
{
  "errorId": 21,
  "errorCode": "ERROR_RECAPTCHA_TIMEOUT",
  "errorDescription": "No token within timeout_s. Retry, or send a larger timeout_s."
}
  • Errors answer HTTP 200 too. Check errorId first: 0 is success (or status:"processing" while a task runs). Anything else carries an errorCode and a readable errorDescription. Stop polling as soon as errorId is not 0.
  • Branch on errorCode, not on the description. The description is for people and can change; the codes below are stable.
  • HTTP 502 or 504 means the service is restarting or briefly unreachable. Retry in a few seconds.

Quick triage

Most callers only need to know which of three things to do.

Retry

Nothing is wrong with the request. Send it again; back off for a rate limit.

Don't retry this task

The site key, domain or token can't work. Fix the input, or start a new task.

All error codes

Filter by solver. Link to a code directly with /errors#ERROR_…, or to one solver's list with /errors#turnstile, #v3 or #v2.

errorCodeerrorIdSolversMeaningWhat to do
ERROR_KEY_DOES_NOT_EXIST1Turnstilev3v2The clientKey is missing or wrong.FixSend your key as clientKey in the JSON body.
ERROR_TASK_ABSENT1Turnstilev3v2The body has no task object.FixWrap the fields in {"clientKey": …, "task": {…}}.
ERROR_TASK_TYPE_NOT_SUPPORTED1Turnstilev3v2Unknown task.type, or a type this path doesn't serve.FixUse a task type from that solver's docs, on its own path: Turnstile tasks go to /turnstile/getToken, reCAPTCHA v3 and v2 tasks to /recaptcha/getToken.
ERROR_TASK_INVALID1Turnstilev3v2A field is missing or invalid, for example websiteURL without http(s)://, a missing pageAction or apiJs (reCAPTCHA v3), or a non-numeric timeout_s. Turnstile: the websiteKey is not valid on websiteURL.FixerrorDescription names the field. Fix it and send the task again. Turnstile: copy the widget's data-sitekey from that page.
ERROR_PROXY_NOT_ALLOWED1Turnstilev3v2This key may not send a proxy, or per-request proxies are turned off.FixUse the …ProxyLess task type, or a key that allows proxies.
ERROR_RATE_LIMIT1Turnstilev3v2Too many new tasks from your IP in the last minute.RetryBack off for a few seconds, then retry.
ERROR_METHOD_NOT_ALLOWED1Turnstilev3v2The wrong HTTP method for this endpoint, for example a GET on getToken (or an API URL opened in a browser). It answers HTTP 405.FixUse POST with a JSON body. health and whoami take GET.
ERROR_TASKID_INVALID1Turnstilev3v2getTaskResult was called without a taskId.FixSend the taskId that createTask returned.
ERROR_NO_SUCH_CAPCHA_ID1Turnstilev3v2Unknown taskId, or the task finished more than 10 minutes ago.New taskCheck the id; if it expired, create a new task.
ERROR_NO_SLOT_AVAILABLE2Turnstilev3v2The service is busy or briefly unavailable.RetryRetry in a few seconds. If it keeps happening, check the Status page.
ERROR_CAPTCHA_UNSOLVABLE12Turnstilev3v2No token this time.RetryRetry; a second attempt often succeeds. reCAPTCHA v3: the exact pageAction and a high-score type (ReCaptchaV3HSTask…) help. Turnstile: also when timeout_s runs out; send a larger timeout_s (up to 180 s).
ERROR_RECAPTCHA_TIMEOUT21v3v2No token within timeout_s. Defaults: v3 60 s, v2 120 s.RetryRetry, or send a larger timeout_s (up to 270 s).
ERROR_PROXY_CONNECTION_FAILED25Turnstilev3v2Could not connect through the proxy you sent.FixCheck its address, port and login, or use a ProxyLess type.
ERROR_RECAPTCHA_INVALID_SITEKEY31v3v2Google rejected the websiteKey: mistyped, or the wrong key type.Don't retryv2: copy the checkbox's data-sitekey. v3: copy the render= key from apiJs; if apiJs has render=explicit (or no render=), search the page source for the 6L… key.
ERROR_RECAPTCHA_INVALID_DOMAIN32v3v2The websiteKey is not registered for the domain of websiteURL.Don't retryCheck websiteURL: send the URL of the page that shows the captcha.
ERROR_TOKEN_EXPIRED33v3v2The token is over 120 s old and Google no longer accepts it: getTaskResult was read too late.New taskCreate a new task, and use tokens as soon as they arrive.

Tokens are single-use. reCAPTCHA v3 and v2 tokens expire 120 s after they are issued, Turnstile tokens after 300 s: submit every token right away.

May we load Google reCAPTCHA? It sets a cookie and sends Google details of your device and this visit, which helps us test our service. The site works the same either way, and you can change this anytime under Privacy choices at the bottom of each page. Privacy