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.
{
"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
errorIdfirst:0is success (orstatus:"processing"while a task runs). Anything else carries anerrorCodeand a readableerrorDescription. Stop polling as soon aserrorIdis 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.
Fix the request
Retrying the same body gives the same answer. Change what the description names.
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.
| errorCode | errorId | Solvers | Meaning | What to do |
|---|---|---|---|---|
ERROR_KEY_DOES_NOT_EXIST | 1 | Turnstilev3v2 | The clientKey is missing or wrong. | FixSend your key as clientKey in the JSON body. |
ERROR_TASK_ABSENT | 1 | Turnstilev3v2 | The body has no task object. | FixWrap the fields in {"clientKey": …, "task": {…}}. |
ERROR_TASK_TYPE_NOT_SUPPORTED | 1 | Turnstilev3v2 | Unknown 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_INVALID | 1 | Turnstilev3v2 | A 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_ALLOWED | 1 | Turnstilev3v2 | This 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_LIMIT | 1 | Turnstilev3v2 | Too many new tasks from your IP in the last minute. | RetryBack off for a few seconds, then retry. |
ERROR_METHOD_NOT_ALLOWED | 1 | Turnstilev3v2 | The 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_INVALID | 1 | Turnstilev3v2 | getTaskResult was called without a taskId. | FixSend the taskId that createTask returned. |
ERROR_NO_SUCH_CAPCHA_ID | 1 | Turnstilev3v2 | Unknown taskId, or the task finished more than 10 minutes ago. | New taskCheck the id; if it expired, create a new task. |
ERROR_NO_SLOT_AVAILABLE | 2 | Turnstilev3v2 | The service is busy or briefly unavailable. | RetryRetry in a few seconds. If it keeps happening, check the Status page. |
ERROR_CAPTCHA_UNSOLVABLE | 12 | Turnstilev3v2 | No 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_TIMEOUT | 21 | v3v2 | No 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_FAILED | 25 | Turnstilev3v2 | Could not connect through the proxy you sent. | FixCheck its address, port and login, or use a ProxyLess type. |
ERROR_RECAPTCHA_INVALID_SITEKEY | 31 | v3v2 | Google 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_DOMAIN | 32 | v3v2 | The 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_EXPIRED | 33 | v3v2 | The 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. |
No codes for this filter.
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.