Error Codes

All error responses from the uCaptcha API follow a consistent format. When an error occurs, the response includes errorId: 1 along with an error code and a human-readable description.

Error Response Format

Modern API

{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "The API key you provided does not exist in our system."
}

Legacy API

Plain text:

ERROR_KEY_DOES_NOT_EXIST

JSON (with json=1):

{
  "status": 0,
  "request": "ERROR_KEY_DOES_NOT_EXIST"
}

---

Error Codes Reference

Error Code	HTTP Status	Description	How to Fix
ERROR_KEY_DOES_NOT_EXIST	401	API key is invalid or does not exist	Verify your API key is correct and has not been deleted
ERROR_WRONG_USER_KEY	401	Invalid API key (legacy API format)	Same as above; check the key parameter
ERROR_ZERO_BALANCE	402	Insufficient account balance	Add funds via the Telegram Mini App or dashboard
ERROR_PAGEURL	400	Missing or invalid websiteURL	Provide a valid, fully-qualified URL (including https://)
ERROR_SITEKEY	400	Missing or invalid websiteKey	Inspect the target page to find the correct site key
ERROR_BAD_PARAMETERS	400	One or more request parameters are invalid	Review the request format and check required fields
ERROR_BAD_PROXY	400	Proxy is invalid or unreachable	Verify the proxy is online and credentials are correct
ERROR_PROXY_FORMAT	400	Proxy string could not be parsed	Use the format type://user:pass@ip:port or user:pass@ip:port with a separate proxyType
ERROR_CAPTCHA_UNSOLVABLE	200	The provider could not solve the captcha	Retry the task; consider trying a different provider or selection mode
ERROR_WRONG_CAPTCHA_ID	404	The specified task ID was not found	Verify the taskId is correct and the task has not expired
ERROR_EMPTY_ACTION	400	Missing action parameter (legacy API)	Include action=get, action=getbalance, action=reportbad, or action=reportgood
CAPCHA_NOT_READY	200	Task is still being processed (legacy API)	Continue polling every 5 seconds
TASK_NOT_SUPPORTED	400	The task type is not recognized	Check the task.type value against supported task types
NO_PROVIDERS_AVAILABLE	400	No provider can handle this task type with the current configuration	Try a different task type, selection mode, or contact support
RATE_LIMITED	429	Too many requests from this IP	Reduce request frequency; the limit is 10,000 requests per 10-second window
IP_BANNED	403	Your IP is not in the API key’s whitelist	Add your IP address to the key’s IP whitelist in the dashboard
ERROR_BANNED	403	Your account has been banned	Contact support for more information

---

Error Handling Best Practices

Implement Retry Logic

Some errors are transient and can be resolved by retrying. The following errors are good candidates for automatic retries:

• ERROR_CAPTCHA_UNSOLVABLE — The captcha may succeed on a second attempt, potentially with a different provider.
• RATE_LIMITED — Wait for the rate limit window to reset (check the X-RateLimit-Reset header), then retry.
• NO_PROVIDERS_AVAILABLE — Temporary provider outage. Wait a few seconds and retry.

Caution

Do not retry errors related to authentication (ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY) or billing (ERROR_ZERO_BALANCE). These require manual intervention.

Check Balance Before Batch Operations

Before submitting a large batch of tasks, call getBalance to verify you have sufficient funds. This avoids wasting time and API calls on tasks that will be rejected with ERROR_ZERO_BALANCE.

import requests

# Check balance first
balance_resp = requests.post("https://api.ucaptcha.net/getBalance", json={
    "clientKey": "YOUR_API_KEY"
}).json()

estimated_cost = num_tasks * 0.003  # Estimate per task

if balance_resp["balance"] < estimated_cost:
    print(f"Insufficient balance: ${balance_resp['balance']:.4f} "
          f"(need ~${estimated_cost:.4f} for {num_tasks} tasks)")
else:
    # Proceed with batch submission
    pass

Distinguish Request Errors from Task Errors

There are two categories of errors:

1. Request errors (errorId: 1) — The API could not process your request. These are returned by createTask, getTaskResult, and other endpoints. Check errorCode in the response.

2. Task errors (errorId: 0, status: "failed") — The request was valid, but the provider could not solve the captcha. These appear in getTaskResult responses. Failed tasks are automatically refunded.

Note

The CAPCHA_NOT_READY code is not an error. It is a normal response from the legacy API indicating the task is still being processed. Continue polling.

Example: Robust Error Handling

import requests
import time

def solve_captcha(client_key, task):
    # Create task
    create_resp = requests.post("https://api.ucaptcha.net/createTask", json={
        "clientKey": client_key,
        "task": task
    }).json()

    if create_resp["errorId"] != 0:
        raise Exception(f"Create failed: {create_resp['errorCode']}")

    task_id = create_resp["taskId"]

    # Poll for result
    for _ in range(60):
        result_resp = requests.post("https://api.ucaptcha.net/getTaskResult", json={
            "clientKey": client_key,
            "taskId": task_id
        }).json()

        if result_resp["errorId"] != 0:
            raise Exception(f"Poll failed: {result_resp['errorCode']}")

        if result_resp["status"] == "ready":
            return result_resp["solution"]

        if result_resp["status"] == "failed":
            raise Exception(f"Task failed: {result_resp.get('errorCode', 'unknown')}")

        time.sleep(5)

    raise TimeoutError("Task did not complete within 5 minutes")