Error Handling

Learn how to handle errors and troubleshoot common issues.

Error Response Format

All errors return JSON with this format:

json

{
  "success": false,
  "error": "Error message description"
}

Common Errors

HTTP Code	Error Message	Cause	Solution
`400`	Invalid API key or account inactive	Wrong API key or disabled account	Check API key in dashboard
`403`	Insufficient credits	No credits remaining	Top up credits
`400`	No file uploaded	Missing captcha parameter	Include CAPTCHA image file
`400`	Invalid file type	Unsupported image format	Use JPG, PNG, or GIF
`400`	File size exceeds 5MB	Image too large	Compress or resize image
`405`	Method not allowed	Using GET instead of POST	Use POST method
`429`	Rate limit exceeded	Too many requests	Wait 1 minute

Error Handling Examples

PHP

php

$result = solveCaptcha($apiKey, $imagePath);

if (!$result['success']) {
    $error = $result['error'];
    
    if (strpos($error, 'Invalid API key') !== false) {
        // Handle invalid API key
        echo "Please check your API key in dashboard";
    } elseif (strpos($error, 'Insufficient credits') !== false) {
        // Handle insufficient credits
        echo "Please top up your credits";
    } else {
        // Handle other errors
        echo "Error: " . $error;
    }
}

Python

python

result = solve_captcha(api_key, image_path)

if not result['success']:
    error = result.get('error', 'Unknown error')
    
    if 'Invalid API key' in error:
        print("Please check your API key")
    elif 'Insufficient credits' in error:
        print("Please top up your credits")
    else:
        print(f"Error: {error}")

See more in PHP Examples and Python Examples