Errors
Errors are returned with HTTP 200 and a JSON body: errorId is non-zero, together with errorCode and errorDescription. Client libraries match on errorId / errorCode.
| Code | Meaning |
|---|---|
ERROR_KEY_DOES_NOT_EXIST |
Invalid or missing clientKey |
ERROR_ZERO_BALANCE |
Not enough balance to create the task |
ERROR_NO_SUCH_CAPCHA_ID |
Unknown taskId or the task has expired |
ERROR_CAPTCHA_UNSOLVABLE |
The captcha could not be solved (funds refunded) |
ERROR_TASK_ABSENT |
The task object is missing |
ERROR_TASK_NOT_SUPPORTED |
Task type is not supported |
ERROR_BAD_PARAMETERS |
Required captcha parameters are missing or have an invalid format |
ERROR_BAD_PROXY |
Incorrect proxy parameters (proxyType/proxyAddress/proxyPort) |
Need help? Contact support.
Python SDK exceptions#
Both clients use the same exceptions:
| Exception | Meaning |
|---|---|
ApiError |
The API returned a non-zero errorId; inspect error_code and error_description |
CaptchaTimeoutError |
The polling window or an HTTP request timed out |
NetworkError |
An HTTP/connection error or a non-JSON response |
ValidationError |
A client-checked argument is invalid, for example an empty API key |
All inherit from CaptchaError. The server also validates task parameters; the SDK does not perform complete local validation. Prefer CaptchaTimeoutError: the legacy alias TimeoutError shares a name with Python’s built-in exception.
Do not automatically resubmit after a timeout: the original task may still be running. Error handling examples.