# Error Codes

Complete list of API error codes and their meanings.

# Error Response Format

When an error occurs, the API returns:

{
  "errorId": 1,
  "errorCode": "ERROR_INVALID_REQUEST",
  "errorDescription": "Detailed error message"
}

# Error Codes Reference

Error ID	Error Code	Description	Solution
0	-	Success (no error)	-
1	`ERROR_INVALID_REQUEST`	Invalid request format	Check JSON syntax and required fields
2	`ERROR_KEY_DOES_NOT_EXIST`	Invalid API key	Verify your API key is correct
3	`ERROR_UNSUPPORTED_CAPTCHA_TYPE`	Unsupported task type	Check supported types
10	`ERROR_LIMIT_EXCEEDED`	Rate limit or balance exceeded	Check balance or wait for daily reset
12	`ERROR_CAPTCHA_UNSOLVABLE`	Failed to solve captcha	Retry the request
16	`ERROR_NO_SUCH_CAPCHA_ID`	Task not found	Task ID is invalid or expired

# Common Errors

# ERROR_KEY_DOES_NOT_EXIST

{
  "errorId": 2,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "Invalid API key"
}

Causes:

API key is incorrect
API key has been regenerated
Account is banned

Solution:

Verify your API key from /panel in Discord
Regenerate key if compromised

# ERROR_LIMIT_EXCEEDED

{
  "errorId": 10,
  "errorCode": "ERROR_LIMIT_EXCEEDED",
  "errorDescription": "Insufficient balance"
}

Causes:

Account balance is zero
Daily free solves exhausted
Plan limits reached

Solution:

Add balance to your account
Use /claim in Discord for daily free solves
Upgrade your plan

# ERROR_CAPTCHA_UNSOLVABLE

{
  "errorId": 12,
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "Failed to solve captcha"
}

Causes:

Captcha is too difficult
Website changed captcha implementation
Temporary solving issues

Solution:

Retry the request (recommended: 3 attempts)
Check if website has updated
Contact support if persistent

# ERROR_UNSUPPORTED_CAPTCHA_TYPE

{
  "errorId": 3,
  "errorCode": "ERROR_UNSUPPORTED_CAPTCHA_TYPE",
  "errorDescription": "Unsupported task type: UnknownTask"
}

Causes:

Task type is misspelled
Task type doesn't exist

Solution:

Check exact task type spelling
See supported types

# Handling Errors

# Python Example

import requests

def solve_with_retry(task, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post("https://v1.captchasolv.com/solve", json={
            "clientKey": API_KEY,
            "task": task
        }).json()
        
        if response["errorId"] == 0:
            return response["solution"]
        
        error_code = response.get("errorCode", "")
        
        # Retry on unsolvable
        if error_code == "ERROR_CAPTCHA_UNSOLVABLE":
            print(f"Attempt {attempt + 1} failed, retrying...")
            continue
        
        # Don't retry on other errors
        raise Exception(f"Error: {response.get('errorDescription')}")
    
    raise Exception("Max retries exceeded")

# JavaScript Example

async function solveWithRetry(task, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        const response = await axios.post('https://v1.captchasolv.com/solve', {
            clientKey: API_KEY,
            task: task
        });
        
        if (response.data.errorId === 0) {
            return response.data.solution;
        }
        
        const errorCode = response.data.errorCode || '';
        
        // Retry on unsolvable
        if (errorCode === 'ERROR_CAPTCHA_UNSOLVABLE') {
            console.log(`Attempt ${attempt + 1} failed, retrying...`);
            continue;
        }
        
        // Don't retry on other errors
        throw new Error(response.data.errorDescription);
    }
    
    throw new Error('Max retries exceeded');
}

# Best Practices

Always check errorId - Even successful responses include this field
Implement retry logic - Retry on ERROR_CAPTCHA_UNSOLVABLE
Don't retry on auth errors - ERROR_KEY_DOES_NOT_EXIST won't succeed on retry
Log errors - Save error details for debugging
Monitor balance - Check balance periodically to avoid disruptions