Cloud Browser API Errors

View as markdown

Copy for LLM

Copy for LLM Open in ChatGPT Open in Claude Open in Perplexity

The Cloud Browser API returns standard HTTP status codes and detailed error information to help you troubleshoot issues. This page lists error codes specific to browser session operations.

Note: The Cloud Browser API uses WebSocket connections. Most errors occur during the initial connection handshake or browser allocation phase.

Browser-Specific Errors

The Cloud Browser API has specific error codes that are unique to browser session operations:

Error Handling Best Practices

Understanding how to handle browser errors is crucial for building robust automation scripts. Different error types require different handling strategies.

Retryable Errors - Automatic Recovery

Some browser errors are transient and can be safely retried. These typically indicate temporary resource unavailability or network issues.

Automatic Retry: For retryable errors, implement exponential backoff (e.g., wait 1s, 2s, 4s) before retrying. Most transient issues resolve within seconds.

Retryable error codes:

• ERR::BROWSER::ALLOCATION_FAILED - Browser pool temporarily saturated
• ERR::BROWSER::CDP_CONNECTION_FAILED - Failed to establish CDP connection
• ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED - WebSocket upgrade failed
• ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST - Concurrent session limit reached
• ERR::BROWSER::PROXY_UNAVAILABLE - Proxy temporarily unavailable

Recommended retry strategy:

from scrapfly import ScrapflyClient
import time

client = ScrapflyClient(api_key="")
max_retries = 3
retry_delay = 1  # seconds

for attempt in range(max_retries):
    try:
        # Connect to browser
        browser = client.create_browser_session(
            country="us",
            proxy_pool="public_residential_pool"
        )
        break  # Success!
    except Exception as e:
        if "ERR::BROWSER::" in str(e) and attempt < max_retries - 1:
            print(f"Retry {attempt + 1}/{max_retries}: {e}")
            time.sleep(retry_delay)
            retry_delay *= 2  # Exponential backoff
        else:
            raise  # Give up after max retries

Non-Retryable Errors - Immediate Action Required

These errors indicate configuration issues, quota limits, or session timeouts that cannot be automatically resolved. You must take action before retrying.

Requires Intervention: Non-retryable errors need manual action - fix configuration, upgrade plan, or wait for quota reset.

Non-retryable error codes:

• ERR::BROWSER::CONFIG_ERROR - Invalid browser configuration parameters
• ERR::BROWSER::QUOTA_LIMIT_REACHED - Monthly browser quota exhausted
• ERR::BROWSER::SESSION_TIMEOUT - Browser session exceeded maximum duration

How to handle non-retryable errors:

1. Config errors: Review the error message and fix invalid parameters
2. Quota reached: Upgrade your plan or wait until quota resets (monthly)
3. Session timeout: Design scripts to complete within session time limits
4. Concurrency limit: Wait for existing sessions to close before starting new ones

try:
    browser = client.create_browser_session(country="us")
except Exception as e:
    if "ERR::BROWSER::QUOTA_LIMIT_REACHED" in str(e):
        print("Monthly quota reached. Upgrade plan or wait for reset.")
        # Notify admin, pause automation, etc.
    elif "ERR::BROWSER::CONFIG_ERROR" in str(e):
        print(f"Configuration error: {e}")
        # Fix parameters and retry
    elif "ERR::BROWSER::SESSION_TIMEOUT" in str(e):
        print("Session timed out. Optimize script to complete faster.")
    else:
        raise  # Unknown error

Connection Lifecycle & Errors

Understanding when errors occur in the browser connection lifecycle helps with debugging and implementing proper error handling.

Connection Phases

1. WebSocket Handshake

   Initial HTTP upgrade to WebSocket connection.

   Possible errors:

   • ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED - Network issues, invalid headers
2. Browser Allocation

   Request browser instance from the pool.

   Possible errors:

   • ERR::BROWSER::ALLOCATION_FAILED - Pool saturated, no available instances
   • ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST - Plan concurrency limit reached
   • ERR::BROWSER::QUOTA_LIMIT_REACHED - Monthly quota exhausted
   • ERR::BROWSER::PROXY_UNAVAILABLE - Requested proxy unavailable
3. CDP Connection

   Establish Chrome DevTools Protocol connection to browser.

   Possible errors:

   • ERR::BROWSER::CDP_CONNECTION_FAILED - Browser crashed, network timeout
   • ERR::BROWSER::CONFIG_ERROR - Invalid CDP configuration
4. Active Session

   Browser session is active and ready for automation commands.

   Possible errors:

   • ERR::BROWSER::SESSION_TIMEOUT - Session exceeded maximum duration

Monitoring Browser Sessions

Track your browser usage to avoid hitting limits and optimize your automation workflows.

Monitoring recommendations:

• Active sessions: Check GET /account endpoint for current concurrent session count
• Monthly quota: Monitor remaining browser hours via dashboard or API
• Session duration: Log session start/end times to optimize scripts
• Error rates: Track error codes to identify patterns (e.g., frequent allocation failures)

{
  "account": {
    "plan": "professional",
    "browser_sessions": {
      "concurrent_limit": 10,
      "concurrent_active": 7,
      "monthly_quota_hours": 100,
      "monthly_quota_used_hours": 73.5,
      "monthly_quota_remaining_hours": 26.5
    }
  }
}

Troubleshooting Common Issues

# Use context manager to ensure sessions are closed
with client.create_browser_session() as browser:
    # Automation code here
    pass
# Session automatically closed after block

HTTP Status Codes

Error Response Format

Browser API errors are returned via WebSocket messages in a consistent format:

{
  "type": "error",
  "error": {
    "code": "ERR::BROWSER::ALLOCATION_FAILED",
    "message": "Failed to allocate a browser instance from the pool",
    "retryable": true,
    "http_code": 503,
    "details": {
      "pool_status": "saturated",
      "retry_after_seconds": 5
    }
  }
}

Error message fields:

• type - Always "error" for error messages
• error.code - Machine-readable error code (e.g., ERR::BROWSER::ALLOCATION_FAILED)
• error.message - Human-readable error description
• error.retryable - Whether the operation can be retried
• error.http_code - HTTP status code equivalent
• error.details - Additional context-specific details (optional)

Related Documentation

• Cloud Browser API Getting Started
• Cloud Browser API Billing
• Using Playwright with Cloud Browser API
• Using Puppeteer with Cloud Browser API
• Using Selenium with Cloud Browser API
• Contact Support