# Scrapfly Documentation ## Table of Contents ### Dashboard - [Intro](https://scrapfly.io/docs) - [Project](https://scrapfly.io/docs/project) - [Account](https://scrapfly.io/docs/account) - [Workspace & Team](https://scrapfly.io/docs/workspace-and-team) - [Billing](https://scrapfly.io/docs/billing) ### Products #### MCP Server - [Getting Started](https://scrapfly.io/docs/mcp/getting-started) - [Tools & API Spec](https://scrapfly.io/docs/mcp/tools) - [Authentication](https://scrapfly.io/docs/mcp/authentication) - [Examples & Use Cases](https://scrapfly.io/docs/mcp/examples) - [FAQ](https://scrapfly.io/docs/mcp/faq) ##### Integrations - [Overview](https://scrapfly.io/docs/mcp/integrations) - [Claude Desktop](https://scrapfly.io/docs/mcp/integrations/claude-desktop) - [Claude Code](https://scrapfly.io/docs/mcp/integrations/claude-code) - [ChatGPT](https://scrapfly.io/docs/mcp/integrations/chatgpt) - [Cursor](https://scrapfly.io/docs/mcp/integrations/cursor) - [Cline](https://scrapfly.io/docs/mcp/integrations/cline) - [Windsurf](https://scrapfly.io/docs/mcp/integrations/windsurf) - [Zed](https://scrapfly.io/docs/mcp/integrations/zed) - [Roo Code](https://scrapfly.io/docs/mcp/integrations/roo-code) - [VS Code](https://scrapfly.io/docs/mcp/integrations/vscode) - [LangChain](https://scrapfly.io/docs/mcp/integrations/langchain) - [LlamaIndex](https://scrapfly.io/docs/mcp/integrations/llamaindex) - [CrewAI](https://scrapfly.io/docs/mcp/integrations/crewai) - [OpenAI](https://scrapfly.io/docs/mcp/integrations/openai) - [n8n](https://scrapfly.io/docs/mcp/integrations/n8n) - [Make](https://scrapfly.io/docs/mcp/integrations/make) - [Zapier](https://scrapfly.io/docs/mcp/integrations/zapier) - [Vapi AI](https://scrapfly.io/docs/mcp/integrations/vapi) - [Agent Builder](https://scrapfly.io/docs/mcp/integrations/agent-builder) - [Custom Client](https://scrapfly.io/docs/mcp/integrations/custom-client) #### Web Scraping API - [Getting Started](https://scrapfly.io/docs/scrape-api/getting-started) - [API Specification]() - [Monitoring](https://scrapfly.io/docs/monitoring) - [Customize Request](https://scrapfly.io/docs/scrape-api/custom) - [Debug](https://scrapfly.io/docs/scrape-api/debug) - [Anti Scraping Protection](https://scrapfly.io/docs/scrape-api/anti-scraping-protection) - [Proxy](https://scrapfly.io/docs/scrape-api/proxy) - [Proxy Mode](https://scrapfly.io/docs/scrape-api/proxy-mode) - [Proxy Mode - Screaming Frog](https://scrapfly.io/docs/scrape-api/proxy-mode/screaming-frog) - [Proxy Mode - Apify](https://scrapfly.io/docs/scrape-api/proxy-mode/apify) - [(Auto) Data Extraction](https://scrapfly.io/docs/scrape-api/extraction) - [Javascript Rendering](https://scrapfly.io/docs/scrape-api/javascript-rendering) - [Javascript Scenario](https://scrapfly.io/docs/scrape-api/javascript-scenario) - [SSL](https://scrapfly.io/docs/scrape-api/ssl) - [DNS](https://scrapfly.io/docs/scrape-api/dns) - [Cache](https://scrapfly.io/docs/scrape-api/cache) - [Batch (Multi-URL Scraping)](https://scrapfly.io/docs/scrape-api/batch) - [Session](https://scrapfly.io/docs/scrape-api/session) - [Webhook](https://scrapfly.io/docs/scrape-api/webhook) - [Screenshot](https://scrapfly.io/docs/scrape-api/screenshot) - [Errors](https://scrapfly.io/docs/scrape-api/errors) - [Timeout](https://scrapfly.io/docs/scrape-api/understand-timeout) - [Throttling](https://scrapfly.io/docs/throttling) - [Troubleshoot](https://scrapfly.io/docs/scrape-api/troubleshoot) - [Billing](https://scrapfly.io/docs/scrape-api/billing) - [FAQ](https://scrapfly.io/docs/scrape-api/faq) #### Crawler API - [Getting Started](https://scrapfly.io/docs/crawler-api/getting-started) - [API Specification]() - [Retrieving Results](https://scrapfly.io/docs/crawler-api/results) - [WARC Format](https://scrapfly.io/docs/crawler-api/warc-format) - [Data Extraction](https://scrapfly.io/docs/crawler-api/extraction-rules) - [Webhook](https://scrapfly.io/docs/crawler-api/webhook) - [Billing](https://scrapfly.io/docs/crawler-api/billing) - [Errors](https://scrapfly.io/docs/crawler-api/errors) - [Troubleshoot](https://scrapfly.io/docs/crawler-api/troubleshoot) - [FAQ](https://scrapfly.io/docs/crawler-api/faq) #### Screenshot API - [Getting Started](https://scrapfly.io/docs/screenshot-api/getting-started) - [API Specification]() - [Accessibility Testing](https://scrapfly.io/docs/screenshot-api/accessibility) - [Webhook](https://scrapfly.io/docs/screenshot-api/webhook) - [Billing](https://scrapfly.io/docs/screenshot-api/billing) - [Errors](https://scrapfly.io/docs/screenshot-api/errors) #### Extraction API - [Getting Started](https://scrapfly.io/docs/extraction-api/getting-started) - [API Specification]() - [Rules Template](https://scrapfly.io/docs/extraction-api/rules-and-template) - [LLM Extraction](https://scrapfly.io/docs/extraction-api/llm-prompt) - [AI Auto Extraction](https://scrapfly.io/docs/extraction-api/automatic-ai) - [Webhook](https://scrapfly.io/docs/extraction-api/webhook) - [Billing](https://scrapfly.io/docs/extraction-api/billing) - [Errors](https://scrapfly.io/docs/extraction-api/errors) - [FAQ](https://scrapfly.io/docs/extraction-api/faq) #### Proxy Saver - [Getting Started](https://scrapfly.io/docs/proxy-saver/getting-started) - [Fingerprints](https://scrapfly.io/docs/proxy-saver/fingerprints) - [Optimizations](https://scrapfly.io/docs/proxy-saver/optimizations) - [SSL Certificates](https://scrapfly.io/docs/proxy-saver/certificates) - [Protocols](https://scrapfly.io/docs/proxy-saver/protocols) - [Pacfile](https://scrapfly.io/docs/proxy-saver/pacfile) - [Secure Credentials](https://scrapfly.io/docs/proxy-saver/security) - [Billing](https://scrapfly.io/docs/proxy-saver/billing) #### Cloud Browser API - [Getting Started](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Proxy & Geo-Targeting](https://scrapfly.io/docs/cloud-browser-api/proxy) - [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock) - [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads) - [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume) - [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) - [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode) - [Bring Your Own Proxy](https://scrapfly.io/docs/cloud-browser-api/bring-your-own-proxy) - [Browser Extensions](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Native Browser MCP](https://scrapfly.io/docs/cloud-browser-api/mcp) - [DevTools Protocol](https://scrapfly.io/docs/cloud-browser-api/cdp-reference) ##### Integrations - [Puppeteer](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - [Playwright](https://scrapfly.io/docs/cloud-browser-api/playwright) - [Selenium](https://scrapfly.io/docs/cloud-browser-api/selenium) - [Vercel Agent Browser](https://scrapfly.io/docs/cloud-browser-api/agent-browser) - [Browser Use](https://scrapfly.io/docs/cloud-browser-api/browser-use) - [Stagehand](https://scrapfly.io/docs/cloud-browser-api/stagehand) - [Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - [Errors](https://scrapfly.io/docs/cloud-browser-api/errors) ### Tools - [Antibot Detector](https://scrapfly.io/docs/tools/antibot-detector) ### SDK - [Golang](https://scrapfly.io/docs/sdk/golang) - [Python](https://scrapfly.io/docs/sdk/python) - [Rust](https://scrapfly.io/docs/sdk/rust) - [TypeScript](https://scrapfly.io/docs/sdk/typescript) - [Scrapy](https://scrapfly.io/docs/sdk/scrapy) ### Integrations - [Getting Started](https://scrapfly.io/docs/integration/getting-started) - [LangChain](https://scrapfly.io/docs/integration/langchain) - [LlamaIndex](https://scrapfly.io/docs/integration/llamaindex) - [CrewAI](https://scrapfly.io/docs/integration/crewai) - [Zapier](https://scrapfly.io/docs/integration/zapier) - [Make](https://scrapfly.io/docs/integration/make) - [n8n](https://scrapfly.io/docs/integration/n8n) ### Academy - [Overview](https://scrapfly.io/academy) - [Web Scraping Overview](https://scrapfly.io/academy/scraping-overview) - [Tools](https://scrapfly.io/academy/tools-overview) - [Reverse Engineering](https://scrapfly.io/academy/reverse-engineering) - [Static Scraping](https://scrapfly.io/academy/static-scraping) - [HTML Parsing](https://scrapfly.io/academy/html-parsing) - [Dynamic Scraping](https://scrapfly.io/academy/dynamic-scraping) - [Hidden API Scraping](https://scrapfly.io/academy/hidden-api-scraping) - [Headless Browsers](https://scrapfly.io/academy/headless-browsers) - [Hidden Web Data](https://scrapfly.io/academy/hidden-web-data) - [JSON Parsing](https://scrapfly.io/academy/json-parsing) - [Data Processing](https://scrapfly.io/academy/data-processing) - [Scaling](https://scrapfly.io/academy/scaling) - [Walkthrough Summary](https://scrapfly.io/academy/walkthrough-summary) - [Scraper Blocking](https://scrapfly.io/academy/scraper-blocking) - [Proxies](https://scrapfly.io/academy/proxies) --- # Cloud Browser API Errors [ View as markdown ](https://scrapfly.io/?view=markdown) Copy for LLM Copy for LLM [ Open in ChatGPT ](https://chatgpt.com/?hints=search&prompt=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Ferrors%20so%20I%20can%20ask%20questions%20about%20it.) [ Open in Claude ](https://claude.ai/new?q=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Ferrors%20so%20I%20can%20ask%20questions%20about%20it.) [ Open in Perplexity ](https://www.perplexity.ai/search/new?q=Read%20from%20https%3A%2F%2Fscrapfly.io%2Fdocs%2Fcloud-browser-api%2Ferrors%20so%20I%20can%20ask%20questions%20about%20it.) 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: #### [ ERR::BROWSER::ALLOCATION\_FAILED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::ALLOCATION_FAILED) Failed to allocate a browser instance from the pool - **Retryable:** Yes - **HTTP status code:** `503` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::ALLOCATION_FAILED) #### [ ERR::BROWSER::BYOP\_CUSTOM\_PLAN\_REQUIRED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_CUSTOM_PLAN_REQUIRED) BYOP (Bring Your Own Proxy) feature requires a Custom plan subscription - **Retryable:** No - **HTTP status code:** `403` - **Documentation:** - [BYOP Documentation](https://scrapfly.io/docs/cloud-browser-api/byop) - [Contact Sales](https://scrapfly.io/contact) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_CUSTOM_PLAN_REQUIRED) #### [ ERR::BROWSER::BYOP\_INVALID\_PROXY\_FORMAT ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_INVALID_PROXY_FORMAT) Invalid BYOP proxy URL format. Expected: {protocol}://{user}:{pass}@{host}:{port} - **Retryable:** No - **HTTP status code:** `400` - **Documentation:** - [BYOP Documentation](https://scrapfly.io/docs/cloud-browser-api/byop) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_INVALID_PROXY_FORMAT) #### [ ERR::BROWSER::BYOP\_PROXY\_UNREACHABLE ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_PROXY_UNREACHABLE) BYOP proxy connectivity test failed. The proxy is unreachable, rejected the connection, or returned an authentication/whitelist error. The reason from the proxy is included in the response message. - **Retryable:** No - **HTTP status code:** `503` - **Documentation:** - [BYOP Documentation](https://scrapfly.io/docs/cloud-browser-api/byop) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_PROXY_UNREACHABLE) #### [ ERR::BROWSER::CDP\_CONNECTION\_FAILED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CDP_CONNECTION_FAILED) Failed to establish CDP connection to the browser - **Retryable:** Yes - **HTTP status code:** `502` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CDP_CONNECTION_FAILED) #### [ ERR::BROWSER::CONFIG\_ERROR ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CONFIG_ERROR) Browser configuration error - **Retryable:** No - **HTTP status code:** `400` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CONFIG_ERROR) #### [ ERR::BROWSER::EXTENSION\_DOWNLOAD\_FAILED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_DOWNLOAD_FAILED) Failed to download browser extension from storage - **Retryable:** Yes - **HTTP status code:** `503` - **Documentation:** - [Extensions Documentation](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_DOWNLOAD_FAILED) #### [ ERR::BROWSER::EXTENSION\_INVALID ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_INVALID) Invalid browser extension. Ensure the ZIP contains a valid manifest.json - **Retryable:** No - **HTTP status code:** `422` - **Documentation:** - [Extensions Documentation](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_INVALID) #### [ ERR::BROWSER::EXTENSION\_NOT\_FOUND ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_NOT_FOUND) Browser extension not found - **Retryable:** No - **HTTP status code:** `404` - **Documentation:** - [Extensions Documentation](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_NOT_FOUND) #### [ ERR::BROWSER::EXTENSION\_QUOTA\_EXCEEDED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_QUOTA_EXCEEDED) Browser extension quota exceeded for your subscription plan - **Retryable:** No - **HTTP status code:** `403` - **Documentation:** - [Extensions Documentation](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_QUOTA_EXCEEDED) - [Upgrade Subscription](https://scrapfly.io/pricing) #### [ ERR::BROWSER::NAVIGATION\_TIMEOUT ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::NAVIGATION_TIMEOUT) Page navigation timed out before completion - **Retryable:** Yes - **HTTP status code:** `504` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::NAVIGATION_TIMEOUT) #### [ ERR::BROWSER::PROXY\_UNAVAILABLE ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::PROXY_UNAVAILABLE) The proxy for the browser session is unavailable - **Retryable:** Yes - **HTTP status code:** `422` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::PROXY_UNAVAILABLE) #### [ ERR::BROWSER::QUOTA\_LIMIT\_REACHED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::QUOTA_LIMIT_REACHED) You reached your browser quota limit for the month - **Retryable:** No - **HTTP status code:** `429` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::QUOTA_LIMIT_REACHED) - [Upgrade your subscription](https://scrapfly.io/pricing) #### [ ERR::BROWSER::SESSION\_TIMEOUT ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::SESSION_TIMEOUT) Browser session exceeded maximum duration - **Retryable:** No - **HTTP status code:** `408` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::SESSION_TIMEOUT) #### [ ERR::BROWSER::TOO\_MANY\_CONCURRENT\_REQUEST ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST) You reached the concurrent limit of browser sessions for your current plan - **Retryable:** Yes - **HTTP status code:** `429` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Quota Pricing](https://scrapfly.io/pricing) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST) #### [ ERR::BROWSER::UNBLOCK\_FAILED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::UNBLOCK_FAILED) Failed to bypass anti-bot protection for the target URL - **Retryable:** Yes - **HTTP status code:** `503` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::UNBLOCK_FAILED) #### [ ERR::BROWSER::WEBSOCKET\_UPGRADE\_FAILED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED) Failed to upgrade connection to WebSocket - **Retryable:** Yes - **HTTP status code:** `400` - **Documentation:** - [Browser Documentation](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED) ## 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` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::ALLOCATION_FAILED) - Browser pool temporarily saturated - [ `ERR::BROWSER::CDP_CONNECTION_FAILED` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CDP_CONNECTION_FAILED) - Failed to establish CDP connection - [ `ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::WEBSOCKET_UPGRADE_FAILED) - WebSocket upgrade failed - [ `ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::TOO_MANY_CONCURRENT_REQUEST) - Concurrent session limit reached - [ `ERR::BROWSER::PROXY_UNAVAILABLE` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::PROXY_UNAVAILABLE) - Proxy temporarily unavailable - [ `ERR::BROWSER::EXTENSION_DOWNLOAD_FAILED` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_DOWNLOAD_FAILED) - Extension download temporarily failed (storage issue) **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` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::CONFIG_ERROR) - Invalid browser configuration parameters - [ `ERR::BROWSER::QUOTA_LIMIT_REACHED` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::QUOTA_LIMIT_REACHED) - Monthly browser quota exhausted - [ `ERR::BROWSER::SESSION_TIMEOUT` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::SESSION_TIMEOUT) - Browser session exceeded maximum duration - [ `ERR::BROWSER::EXTENSION_NOT_FOUND` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_NOT_FOUND) - Extension ID does not exist or was deleted - [ `ERR::BROWSER::EXTENSION_INVALID` ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::EXTENSION_INVALID) - Extension package is invalid or corrupted **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 - `ERR::BROWSER::EXTENSION_NOT_FOUND` - Extension ID not found in storage - `ERR::BROWSER::EXTENSION_INVALID` - Extension package invalid or corrupted - `ERR::BROWSER::EXTENSION_DOWNLOAD_FAILED` - Failed to download extension (retryable) 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 ##### Frequent `ALLOCATION_FAILED` errors **Cause:** Browser pool is temporarily saturated (high demand). **Solutions:** - Implement exponential backoff retry logic (wait 1s, 2s, 4s, 8s) - Reduce concurrent session usage during peak hours - Upgrade to a plan with dedicated browser instances - Contact support if issue persists for extended periods ##### `TOO_MANY_CONCURRENT_REQUEST` errors **Cause:** You've reached your plan's concurrent browser session limit. **Solutions:** - Close unused browser sessions before starting new ones - Implement session pooling to reuse browsers across tasks - Queue automation tasks to run sequentially instead of in parallel - Upgrade to a plan with higher concurrency limits ``` # Use context manager to ensure sessions are closed with client.create_browser_session() as browser: # Automation code here pass # Session automatically closed after block ``` ##### `WEBSOCKET_UPGRADE_FAILED` errors **Cause:** Network issues or firewall blocking WebSocket connections. **Solutions:** - Verify your network allows WebSocket connections (not just HTTP/HTTPS) - Check firewall rules for port 443 (wss://) or port 80 (ws://) - Ensure no proxy/middleware is stripping WebSocket upgrade headers - Test with a simple WebSocket client to isolate the issue ##### `SESSION_TIMEOUT` errors **Cause:** Browser session exceeded maximum allowed duration. **Solutions:** - Optimize scripts to complete tasks faster (e.g., reduce wait times) - Split long-running tasks into multiple shorter sessions - Use caching to avoid re-scraping already processed data - Consider using the Crawler API for large-scale, long-running jobs **Note:** Session timeout errors are billed as the session was active until timeout. ##### Extension errors (`EXTENSION_*`) **Extension-related errors occur when using custom browser extensions.** **`EXTENSION_NOT_FOUND`** - Extension ID does not exist - Verify the extension ID is correct in your request - Check the extension exists in your [Extensions dashboard](https://scrapfly.io/dashboard/cloud-browser/extensions) - Re-upload the extension if it was accidentally deleted **`EXTENSION_INVALID`** - Extension package is invalid - Ensure your ZIP contains a valid `manifest.json` at root level - Test your extension locally in Chrome before uploading - Check the [Extensions documentation](https://scrapfly.io/docs/cloud-browser-api/extensions) for packaging requirements **`EXTENSION_DOWNLOAD_FAILED`** - Temporary storage issue (retryable) - This error is **retryable** - implement exponential backoff - Storage issues are usually transient and resolve quickly - Contact support if issue persists for more than a few minutes ## HTTP Status Codes | Status Code | Description | |---|---| | `101 Switching Protocols` | WebSocket connection successfully upgraded | | `400 Bad Request` | Invalid parameters or configuration (ERR::BROWSER::CONFIG\_ERROR) | | `401 Unauthorized` | Invalid or missing API key | | `408 Request Timeout` | Browser session timeout (ERR::BROWSER::SESSION\_TIMEOUT) | | `422 Unprocessable Entity` | Proxy unavailable (ERR::BROWSER::PROXY\_UNAVAILABLE) | | `429 Too Many Requests` | Quota or concurrency limit exceeded | | `502 Bad Gateway` | CDP connection failed (ERR::BROWSER::CDP\_CONNECTION\_FAILED) | | `503 Service Unavailable` | Browser allocation failed (ERR::BROWSER::ALLOCATION\_FAILED) | ## 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](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Cloud Browser API Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - [Using Playwright with Cloud Browser API](https://scrapfly.io/docs/cloud-browser-api/playwright) - [Using Puppeteer with Cloud Browser API](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - [Using Selenium with Cloud Browser API](https://scrapfly.io/docs/cloud-browser-api/selenium) - [Contact Support](https://scrapfly.io/docs/support)