# 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) - [Schedule](https://scrapfly.io/docs/scrape-api/schedule) - [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) - [Schedule](https://scrapfly.io/docs/crawler-api/schedule) - [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) - [Schedule](https://scrapfly.io/docs/screenshot-api/schedule) - [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) - [Saved Templates](https://scrapfly.io/docs/extraction-api/templates) - [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) #### Data API - [Getting Started](https://scrapfly.io/docs/data-api/getting-started) #### 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) - [Captcha Solver](https://scrapfly.io/docs/cloud-browser-api/captcha-solver) - [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 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) Deprecated. Use ERR::BROWSER::BYOP\_FEATURE\_NOT\_ENABLED. Previously fired when BYOP was attempted without a Custom plan subscription. - **Retryable:** No - **HTTP status code:** `403` - **Documentation:** - [BYOP Documentation](https://scrapfly.io/docs/cloud-browser-api/bring-your-own-proxy) - [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\_FEATURE\_NOT\_ENABLED ](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_FEATURE_NOT_ENABLED) BYOP (Bring Your Own Proxy) is not enabled for this account. Can be enabled on CUSTOM plan on request. - **Retryable:** No - **HTTP status code:** `403` - **Documentation:** - [BYOP Documentation](https://scrapfly.io/docs/cloud-browser-api/bring-your-own-proxy) - [Contact Sales](https://scrapfly.io/contact) - [Related Error Doc](https://scrapfly.io/docs/cloud-browser-api/error/ERR::BROWSER::BYOP_FEATURE_NOT_ENABLED) #### [ 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/bring-your-own-proxy) - [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/bring-your-own-proxy) - [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)