ReCAPTCHA

Overview

Google reCAPTCHA is the most popular captcha system in the world, used by millions of websites to protect against spam and bots. Achicaptcha currently supports reCAPTCHA v2 with high success rate.

⚠️

Currently Achicaptcha only supports reCAPTCHA v2. reCAPTCHA v3 and Enterprise are not yet supported.

ReCAPTCHA

1. Create Task

Request

POST https://api.achicaptcha.com/createTask

Parameters

Parameter Name	Data Type	Required?	Description
`clientKey`	string	yes	Api key
`task.type`	string	yes	RecaptchaV2TaskProxyless for ultra-fast solving RecaptchaV2TaskProxylessNormal for normal solving
`task.websiteURL`	string	yes	Website URL containing captcha
`task.websiteKey`	string	yes	reCAPTCHA sitekey

Request Example

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

Response

When successful, server returns errorId = 0 and taskId

{
  "errorId": 0,
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

2. Get Result

Request

POST https://api.achicaptcha.com/getTaskResult

Parameters

Parameter Name	Data Type	Required?	Description
`clientKey`	string	yes	Api key
`taskId`	string	yes	TaskId obtained from (1)

Request Example

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Response

{
  "errorId": 0,
  "status": "ready",
  "solution": "03AGdBq27QGA96FJRo3mtz..."
}

Status Explanation

errorId = 0 and status = ready: Successfully solved, read result in solution
errorId = 0 and status = processing: Solving captcha, wait 2 seconds and try again
errorId > 0: System error, returns error code and description

Integration Examples

import requests
import time
 
def solve_recaptcha_v2(website_url, website_key, api_key='YOUR_API_KEY'):
    # Step 1: Create task
    create_task_url = 'https://api.achicaptcha.com/createTask'
    create_task_payload = {
        'clientKey': api_key,
        'task': {
            'type': 'RecaptchaV2TaskProxyless',
            'websiteURL': website_url,
            'websiteKey': website_key
        }
    }
    
    response = requests.post(create_task_url, json=create_task_payload)
    result = response.json()
    
    if result['errorId'] != 0:
        raise Exception(result['errorDescription'])
    
    task_id = result['taskId']
    
    # Step 2: Get result
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Wait 2 seconds
        
        get_result_payload = {
            'clientKey': api_key,
            'taskId': task_id
        }
        
        response = requests.post(get_result_url, json=get_result_payload)
        result = response.json()
        
        if result['errorId'] != 0:
            raise Exception(result['errorDescription'])
        
        if result['status'] == 'ready':
            return result['solution']
        
        # If status == 'processing', continue loop
 
# Usage
website_url = 'https://www.google.com/recaptcha/api2/demo'
website_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
token = solve_recaptcha_v2(website_url, website_key, 'YOUR_API_KEY')
print('reCAPTCHA token:', token)

Common Error Codes

Error Code	Description	Notes
0	success	Success
1	processing	Processing
2	missing required fields	Missing required fields, check parameters again
3	task not supported	Task type not supported
4	task creation failed	Task creation failed
5	client key does not exist	API key does not exist, check API key again
6	insufficient account balance	Insufficient account balance, add more credits
7	task failed, please create a new task	Task failed, please create a new task
8	task ID does not exist	Task ID does not exist

Best Practices

For best results when using Achicaptcha API, follow these principles:

1. Validate Site Key

Check site key before sending request
Ensure site key obtained from data-sitekey attribute is accurate
Verify website URL matches page containing captcha

2. Handle Timeouts

Token has expiration time (usually 120 seconds)
Use token immediately after receiving
Don't cache token for too long

3. Polling Interval

Wait at least 2 seconds between result checks
Don't spam API with too many consecutive requests
Set timeout to avoid infinite loops (recommended 120 seconds)

4. Retry Logic

Implement retry for temporary errors like ERROR_NO_SLOT_AVAILABLE
Use exponential backoff when retrying
Limit maximum retry attempts

5. API Key Security

Don't hardcode API key in code
Use environment variables
Don't expose API key on client-side

Useful links:

Image Geetest Captcha