Skip to main content

​
Error Response Format

When an error occurs, the response includes: 
{
  "errorId": 1,
  "errorCode": "ERROR_CODE_HERE",
  "errorDescription": "Human-readable description."
}

​
Authentication Errors

Error CodeHTTPDescription
ERROR_KEY_DOES_NOT_EXIST404API key not found or invalid
ERROR_ACCOUNT_SUSPENDED403User account has been suspended
ERROR_PACKAGE_PAUSED403Package is currently paused
ERROR_PACKAGE_EXPIRED403Package subscription has expired
ERROR_ZERO_BALANCE402Insufficient balance for the operation
ERROR_DATABASE_BALANCE503Balance deduction failed temporarily

​
Validation Errors

Error CodeHTTPDescription
ERROR_MISSING_REQUEST_DATA400Request payload is missing or empty
ERROR_TASK_NOT_SUPPORTED400Task type is not FunCaptchaTask
ERROR_INVALID_PUBLIC_KEY400Public key is not a valid UUID
ERROR_MISSING_WEBSITE_URL400websiteURL field is required
ERROR_MISSING_PUBLIC_KEY400websitePublicKey field is required
ERROR_MISSING_PROXY400proxy field is required
ERROR_MISSING_WEBSITE_SUBDOMAIN400websiteSubdomain field is required
ERROR_INVALID_EXTRA_DATA400data field is not valid JSON
ERROR_INVALID_HEADERS400headers field is not a valid JSON object
ERROR_MISSING_USER_AGENT400User-Agent is required when sec-ch-* headers are provided

​
Proxy Errors

Error CodeHTTPDescription
ERROR_INVALID_PROXY_PROTOCOL400Protocol must be http, socks4, or socks5
ERROR_INVALID_PROXY_PORT400Port must be between 1 and 65535
ERROR_INVALID_PROXY_AUTH400Proxy authentication (user:pass) is missing
ERROR_INVALID_PROXY_FORMAT400Proxy string doesn’t match expected format
ERROR_PROXY_CONNECTION503Could not connect through the proxy

​
Rate Limit Errors

Error CodeHTTPDescription
ERROR_RATE_LIMIT_EXCEEDED429Daily or hourly quota exceeded
ERROR_THREAD_THRESHOLD_EXCEEDED429Too many concurrent tasks for this user

​
Task Errors

Error CodeHTTPDescription
ERROR_TASK_NOT_FOUND404Task ID doesn’t exist or has expired
ERROR_TASK_EXCEPTION500Internal error during task execution
ERROR_TASK_CANCELLED500Task was cancelled due to an internal error
ERROR_TASK_TIMEOUT504Task exceeded the 300-second total timeout
ERROR_SOLVE_TIMEOUT504Solve phase exceeded the 120-second timeout
ERROR_CAPTCHA_UNSOLVABLE403Failed to solve the CAPTCHA challenge
ERROR_PROCESSING_IMAGE504Processing timed out

​
Service Errors

Error CodeHTTPDescription
ERROR_SERVICE_UNAVALIABLE503Service is temporarily disabled
ERROR_TEMPLATE_NOT_FOUND404No Arkose template found for this public key
ERROR_FINGERPRINT_UNAVAILABLE503Service temporarily unavailable
ERROR_DATABASE_UNAVAILABLE503Service temporarily unavailable
ERROR_INTERNAL_DATABASE500Internal server error

​
Handling Errors

​
Retryable Errors

These errors are temporary and can be retried with backoff:
  • ERROR_SERVICE_UNAVALIABLE
  • ERROR_DATABASE_UNAVAILABLE
  • ERROR_DATABASE_BALANCE
  • ERROR_FINGERPRINT_UNAVAILABLE
  • ERROR_PROXY_CONNECTION
  • ERROR_THREAD_THRESHOLD_EXCEEDED
  • ERROR_SOLVE_TIMEOUT
  • ERROR_PROCESSING_IMAGE

​
Non-Retryable Errors

These errors require fixing the request:
  • All validation errors (ERROR_MISSING_*, ERROR_INVALID_*)
  • ERROR_KEY_DOES_NOT_EXIST
  • ERROR_ACCOUNT_SUSPENDED
  • ERROR_ZERO_BALANCE
  • ERROR_TASK_NOT_SUPPORTED
  • ERROR_TEMPLATE_NOT_FOUND

​
Example Error Handling

RETRYABLE = {
    "ERROR_SERVICE_UNAVALIABLE",
    "ERROR_DATABASE_UNAVAILABLE",
    "ERROR_PROXY_CONNECTION",
    "ERROR_THREAD_THRESHOLD_EXCEEDED",
    "ERROR_SOLVE_TIMEOUT",
    "ERROR_PROCESSING_IMAGE",
}

def create_task_safe(client_key, task, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post("https://api.funbypass.com/createTask", json={
            "clientKey": client_key,
            "task": task
        })
        data = resp.json()

        if data.get("errorId", 0) == 0:
            return data

        error_code = data.get("errorCode", "")
        if error_code in RETRYABLE:
            time.sleep(2 ** attempt)
            continue

        raise Exception(f"{error_code}: {data.get('errorDescription')}")

    raise Exception("Max retries exceeded")