Errors
Every error code of the API: errorId, errorCode, what it means and what to do.
Every answer is HTTP 200 with errorId. 0 means success; otherwise there are errorCode and a human-readable errorDescription:
{
"errorId": 1,
"errorCode": "ERROR_KEY_DOES_NOT_EXIST",
"errorDescription": "Account authorization key not found in the system."
}- Check
errorId != 0, not the HTTP status. - Branch on
errorCode;errorDescriptionis for people and may change. - Ids 1–55 follow the Anti-Captcha registry, ids from 90 are codes of this service. An unknown failure is
ERROR_INTERNAL(90) — nevererrorId: 0. - A failed task is not charged. 2Captcha names of the codes: 2Captcha compatibility.
All codes#
- Meaning
clientKeyis missing, malformed, revoked or unknown.- What to do
- Copy the key again from Dashboard → API keys; check for spaces and line breaks and that it is not a key of another service.
- Meaning
- The key already has the maximum number of tasks in progress (200 by default).
- What to do
- Wait until some tasks finish and retry in 1–2 seconds, or raise the parallel limit of the key in the dashboard.
- Meaning
- The available balance is below the price of the task. Money held for tasks in progress is not available.
- What to do
- Top up the balance. Test keys do not need a balance.
- Meaning
- The request came from an IP address that is not in the key's allowlist.
- What to do
- Add the address or network to the allowlist of the key, or clear the list.
- Meaning
- The task could not be solved after all attempts. The held money is returned — the task is free.
- What to do
- Create a new task. If it repeats, check
websiteURL,websiteKey,isInvisible/pageActionand the proxy.
- Meaning
- Unknown method, wrong HTTP method, or the body is not valid JSON (for example,
taskIdsent as a string). - What to do
- Send
POSTwith a JSON body to a documented method.
- Meaning
- No task with this id in your account, or its result expired (10 minutes after it was solved). Reports about unsolved tasks also get this code.
- What to do
- Check
taskIdand the key — tasks are visible to the account that created them. Fetch results soon after they are ready, or use webhooks.
- Meaning
- Requests from this IP address are blocked because of abuse.
- What to do
- Write to support with your account email and the IP address.
- Meaning
taskis missing or invalid: a required field is empty, a value is out of range,callbackUrlis not a public http(s) URL, or the body is larger than 1 MiB.errorDescriptionnames the field.- What to do
- Fix the field named in
errorDescriptionand send the task again.
- Meaning
- Unknown or disabled task type.
- What to do
- Take the type from getTaskTypes. Names are case-sensitive:
RecaptchaV2TaskProxyless, notReCaptchaV2TaskProxyLess.
- Meaning
- The proxy refused the connection.
- What to do
- Check the address, port and type of the proxy, and that it accepts connections from the internet.
- Meaning
- Connecting to the proxy timed out.
- What to do
- Check that the proxy is online; use a faster one.
- Meaning
- The proxy accepted the connection but did not answer in time.
- What to do
- Use a more stable proxy.
- Meaning
- The proxy IP is blocked by Google or by the site.
- What to do
- Use another proxy, preferably residential or mobile.
- Meaning
- The task was not solved in time: no worker took it within 180 seconds, or the attempts ran out. Not charged.
- What to do
- Create a new task. If it keeps happening, check the status page and your proxy.
- Meaning
- Google rejected the site key.
- What to do
- Take
websiteKeyfrom the page again (data-sitekeyor thekparameter); do not mix v2, v3 and Enterprise keys.
- Meaning
- The site key is not valid for the domain of
websiteURL. - What to do
- Pass the address of the page where the widget is really shown.
- Meaning
- The site considers the browser outdated.
- What to do
- Pass a current desktop
userAgent.
- Meaning
- The proxy does not load images (a compatibility code).
- What to do
- Use another proxy.
- Meaning
- Wrong proxy login or password.
- What to do
- Check
proxyLoginandproxyPassword.
- Meaning
- The widget type does not match
isInvisible: an invisible reCAPTCHA sent as visible or the other way round. - What to do
- Set
isInvisibleaccording to the widget on the page.
- Meaning
- The account is suspended.
- What to do
- Write to support.
- Meaning
- A temporary failure on our side. Any unknown error is reported with this id too — never with
errorId: 0. - What to do
- Retry with a growing pause (1, 2, 4… seconds). If it lasts, check the status page.
- Meaning
- Rate limit: more than 30
createTaskor 50getTaskResultper second for the key, or more than 100 requests per second from one IP. - What to do
- Slow down and retry with a pause; poll each task every 2–3 seconds.
- Meaning
- The daily or monthly spending cap of the key is reached.
- What to do
- Raise or remove the cap in the key settings, or wait for the next day or month.