Error Codes

All error responses follow the same format with errorId: 1.

Error Response Format

json

{
  "errorId": 1,
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "solve failed (pass=False, status=200)"
}

ERROR_KEY_DOES_NOT_EXIST

The clientKey provided is not valid.

Action: Check your API key.

ERROR_BAD_REQUEST

The request body is malformed or not valid JSON.

Action: Verify your request body is valid JSON.

ERROR_TASK_NOT_SUPPORTED

Missing required fields (websiteKey or websiteURL).

Action: Ensure both websiteKey and websiteURL are provided.

ERROR_NO_SUCH_CAPCHA_ID

The taskId does not exist or has expired.

Action: Create a new task. Tasks expire after 5 minutes.

ERROR_CAPTCHA_UNSOLVABLE

The captcha could not be solved. Common causes: image recognition failure, worker timeout, or hCaptcha rejected the solution.

Action: Retry with a new task. If persistent, check /health for worker status.

ERROR_CAPTCHA_UNSOLVABLE — safe to retry immediately with a new task
ERROR_NO_SUCH_CAPCHA_ID — task expired, create a new one
ERROR_KEY_DOES_NOT_EXIST — do not retry, fix your key
If workers_connected is 0 on /health, wait for workers to reconnect before retrying