Skip to main content
Twitter may lock your account and require CAPTCHA verification when it detects suspicious activity. Twikit provides automated CAPTCHA solving through Capsolver integration to handle these situations.

​
Overview

When Twitter locks your account (error code 326), you’ll be prompted to solve a FunCAPTCHA challenge to regain access. Instead of manually solving these CAPTCHAs, you can configure Twikit to automatically unlock your account using Capsolver.
Capsolver is a third-party CAPTCHA solving service. You’ll need to sign up at capsolver.com and obtain an API key.

​
Setting up Capsolver

First, initialize the Capsolver instance with your API key: 
from twikit import Capsolver, Client

# Create Capsolver instance
solver = Capsolver(
    api_key='your_capsolver_api_key',
    max_attempts=10,
    get_result_interval=1.0,
    use_blob_data=False
)

# Pass the solver to the client
client = Client(captcha_solver=solver)

​
Configuration parameters

  • api_key (required): Your Capsolver API key obtained from capsolver.com
  • max_attempts (optional): Maximum number of attempts to solve the CAPTCHA (default: 3)
  • get_result_interval (optional): Time in seconds between result checks (default: 1.0)
  • use_blob_data (optional): Whether to use blob data in requests (default: False)

​
How it works

When you initialize the client with a captcha_solver, Twikit automatically handles account locks:
1

Account lock detection

When Twitter returns error code 326, Twikit detects that your account is locked
2

Automatic unlocking

If auto_unlock=True (the default), Twikit automatically calls the unlock process
3

CAPTCHA solving

The Capsolver service solves the FunCAPTCHA challenge and returns the solution token
4

Request retry

Twikit submits the solution and retries your original request
The unlock process happens transparently in the background during your API requests: 
import asyncio
from twikit import Capsolver, Client

async def main():
    solver = Capsolver(api_key='your_api_key')
    client = Client(captcha_solver=solver)
    
    await client.login(
        auth_info_1='username',
        password='password'
    )
    
    # If your account gets locked during this request,
    # it will be automatically unlocked
    user = await client.get_user_by_screen_name('example')
    print(user.name)

asyncio.run(main())

​
Manual unlocking

You can also manually trigger the unlock process: 
await client.unlock()
This method attempts to unlock the account using the configured CAPTCHA solver. It will raise a ValueError if no captcha solver is provided.

​
When CAPTCHAs are triggered

Twitter’s anti-bot detection may lock your account and require CAPTCHA verification in several situations:
  • Too many requests: Sending requests too quickly or exceeding rate limits
  • Suspicious patterns: Automated behavior that doesn’t match normal user activity
  • Multiple logins: Logging in repeatedly from different IPs or locations
  • Account creation: New accounts are more likely to trigger verification
  • Sensitive actions: Mass following, unfollowing, or messaging
Using a CAPTCHA solver doesn’t prevent account locks. Follow best practices in the Account Protection guide to minimize the risk.

​
Troubleshooting

​
”Captcha solver is not provided” error

This error occurs when your account is locked but you haven’t configured a CAPTCHA solver: 
# Wrong - no solver configured
client = Client()
await client.login(...)  # May raise AccountLocked error

# Correct - solver configured
solver = Capsolver(api_key='your_api_key')
client = Client(captcha_solver=solver)
await client.login(...)  # Will auto-unlock if needed

​
Solver fails after max attempts

If the CAPTCHA solver fails after reaching max_attempts, you’ll receive an exception: 
Exception: could not unlock the account.
To resolve this:
  1. Increase the max_attempts parameter
  2. Check your Capsolver API key and account balance
  3. Verify your proxy configuration (if using one)
  4. Try adjusting the use_blob_data parameter

​
Capsolver API errors

If you see error responses from Capsolver:
  • Error ID 1: Service is temporarily unavailable, the solver will retry
  • Invalid API key: Verify your API key is correct
  • Insufficient balance: Add funds to your Capsolver account
Monitor your Capsolver account balance to ensure uninterrupted service. The cost per CAPTCHA solve varies based on complexity.

​
Best practices

  1. Store API keys securely: Use environment variables instead of hardcoding API keys
  2. Set reasonable max_attempts: 3-10 attempts is usually sufficient
  3. Combine with rate limiting: Use CAPTCHA solving alongside proper rate limiting
  4. Monitor costs: Track your Capsolver usage to manage costs
  5. Use proxy rotation: Combine CAPTCHA solving with proxy rotation for better results
import os
from twikit import Capsolver, Client

# Load API key from environment
solver = Capsolver(
    api_key=os.getenv('CAPSOLVER_API_KEY'),
    max_attempts=5
)

client = Client(
    captcha_solver=solver,
    proxy='http://proxy-server:8080'
)

Build docs developers (and LLMs) love

Get started for freeTalk to us