Error Codes

When a render fails after being accepted, the response includes an errorCode that tells you exactly what went wrong and whether you were charged.

How Error Billing Works

Browser7 uses a three-tier error model:

Tier	When It Happens	Charged	Error Code
Pre-flight errors	Request rejected before render starts (400, 401, 402, 429)	No	None (no render created)
User-caused errors	Render ran but failed due to your input or the target site	Yes ($0.01)	Included in response
System errors	Render ran but failed due to Browser7 infrastructure	No ($0.00)	Included in response

User-caused errors are charged because Browser7 consumed resources (residential proxy bandwidth, browser instance, server capacity) attempting the render. The failure was caused by your configuration or the target website.

System errors are never charged. If a render fails due to Browser7 infrastructure issues, no charge is applied to your account balance.

Reading Error Fields

When a render fails, the GET /v1/renders/:id response (HTTP 422) includes error and billing fields:

{
  "status": "failed",
  "errorCode": "RENDER_TIMEOUT",
  "errorMessage": "Overall render exceeded 120 second timeout",
  "billable": true,
  "charged": true,
  "chargedAmountCents": 1,
  "retryAfter": 1
}

Field	Type	Description
errorCode	string	Machine-readable error identifier (see tables below)
errorMessage	string	Human-readable description of what went wrong
billable	boolean	Whether this error type is billable
charged	boolean	Whether a charge was applied to your account balance
chargedAmountCents	number	Amount charged in cents (1 for billable errors, 0 for system errors)

User-Caused Errors (Billable)

These errors mean the render ran and consumed resources, but failed due to your configuration or the target website. You are charged $0.01.

Wait Action Errors

Failures caused by waitFor actions in your request.

Error Code	Description	Common Fix
WAIT_TIMEOUT	Selector or text not found within timeout	Verify selector exists on page; increase timeout
INVALID_SELECTOR	CSS selector syntax is invalid or element doesn't exist	Check CSS selector syntax
INVALID_WAIT_ACTION	Unknown or malformed wait action type	Use valid types: delay, selector, text, click

Timeout Errors

The render or page load exceeded the maximum allowed time.

Error Code	Description	Common Fix
RENDER_TIMEOUT	Overall render exceeded the timeout (default 120s)	Simplify wait actions; check if target site is slow
PAGE_LOAD_TIMEOUT	Page did not stabilize within timeout	Verify the target site loads in a browser

Target Site Errors

The target website is unreachable, broken, or returning errors.

Error Code	Description	Common Fix
INVALID_URL	URL format is invalid	Verify URL includes protocol (https://)
DNS_RESOLUTION_ERROR	Domain cannot be resolved	Check domain spelling; verify the site exists
NETWORK_ERROR	Cannot reach the target site	Verify the site is online; try a different countryCode
SSL_ERROR	SSL/TLS certificate error on the target site	The target site has a certificate issue
HTTP_ERROR	Target site returned an HTTP error (4xx, 5xx)	Check if the site is accessible in a browser

CAPTCHA Errors

CAPTCHA-related failures caused by the target site's configuration.

Error Code	Description	Common Fix
CAPTCHA_TIMEOUT	CAPTCHA solving exceeded timeout	Retry the render; try a different countryCode
INVALID_CAPTCHA_CONFIG	Invalid CAPTCHA configuration in your request	Check the captcha parameter value
CAPTCHA_INJECTION_FAILED	Failed to inject CAPTCHA solution into page	Target site may have changed; retry
CAPTCHA_INVALID_SITEKEY	Target site has an invalid or changed sitekey	Target site changed its CAPTCHA configuration
CAPTCHA_PARAMETERS_NOT_FOUND	Cannot extract CAPTCHA parameters from page	Target site structure changed; contact support if persistent

Geo Configuration Errors

Invalid geographic targeting in your request.

Error Code	Description	Common Fix
INVALID_CITY	City name is not valid for the specified country	Check Supported Countries for available cities
CITY_WITHOUT_COUNTRY	City specified without countryCode	Add countryCode when using city

Generic Errors

Catch-all error codes for unclassified render failures.

Error Code	Description	Common Fix
RENDER_FAILED	Generic render failure	Retry; contact support if persistent
RENDER_ERROR	Generic render error	Retry; contact support if persistent
UNKNOWN	Unclassified error	Retry; contact support if persistent

System Errors (Not Billable)

These errors mean Browser7's infrastructure failed during the render. You are not charged. If you see these frequently, check the API Status Page.

Infrastructure Errors

Error Code	Description	Recommended Action
INTERNAL_ERROR	Internal server error	Retry after a few seconds
DATABASE_ERROR	Database connection or query failure	Retry after a few seconds
SERVICE_UNAVAILABLE	Service was shutting down mid-render	Retry immediately

Browser Engine Errors

Error Code	Description	Recommended Action
BROWSER_ERROR	Browser engine error during render	Retry
BROWSER_CRASH	Browser process crashed	Retry

Proxy Errors

Error Code	Description	Recommended Action
PROXY_PROVIDER_ERROR	Proxy provider outage or error	Retry; try a different countryCode
PROXY_ERROR	Generic proxy failure	Retry

CAPTCHA Service Errors

Failures in the CAPTCHA solving infrastructure. These are Browser7's responsibility, not yours.

Error Code	Description	Recommended Action
CAPTCHA_SERVICE_ERROR	CAPTCHA solving service outage	Retry after a few seconds
CAPTCHA_ALL_SOLVERS_FAILED	All CAPTCHA solvers failed	Retry after a minute
CAPTCHA_HANDLER_NOT_FOUND	No handler configured for CAPTCHA type	Contact support
CAPTCHA_DETECTOR_NOT_FOUND	No detector configured for CAPTCHA type	Contact support
CAPTCHA_SOLVER_NOT_AVAILABLE	Solver API key misconfigured	Retry after a few seconds
CAPTCHA_SOLVER_UNAVAILABLE	Solver service is unreachable	Retry after a few seconds
CAPTCHA_INSUFFICIENT_FUNDS	Solver account issue (Browser7's responsibility)	Retry after a few seconds
CAPTCHA_SUBMIT_FAILED	Solver rejected task submission	Retry
CAPTCHA_SOLVE_FAILED	Solver could not solve the CAPTCHA	Retry
CAPTCHA_SOLVE_TIMEOUT	Solver timed out	Retry
CAPTCHA_PROXY_ERROR	Proxy error during CAPTCHA solving	Retry
CAPTCHA_ERROR	Generic CAPTCHA subsystem failure	Retry
TURNSTILE_RERENDER_FAILED	Turnstile re-render failed	Retry
TURNSTILE_INTERCEPTION_FAILED	Turnstile interception failed	Retry

Pre-Flight Errors

These HTTP errors are returned before the render starts. No render is created, no errorCode is set, and no charge applies to your account balance.

HTTP Status	Error	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient account balance
403	Forbidden	IP not in allowlist
429	Too Many Requests	Concurrent request limit exceeded
503	Service Unavailable	Service temporarily unavailable

See Error Handling for details on these HTTP errors.

Checking Billing in Code

Node.js

const result = await client.render('https://example.com');

if (result.status === 'failed') {
  console.error(`Error: ${result.errorCode} - ${result.errorMessage}`);

  if (result.billable) {
    console.log('Charged: $0.01');
  } else {
    console.log('Not charged (system error)');
    // Safe to retry immediately
  }
}

Python

result = client.render('https://example.com')

if result.status == 'failed':
    print(f'Error: {result.error_code} - {result.error_message}')

    if result.billable:
        print('Charged: $0.01')
    else:
        print('Not charged (system error)')
        # Safe to retry immediately

PHP

$result = $client->render('https://example.com');

if ($result->status === 'failed') {
    echo "Error: {$result->errorCode} - {$result->errorMessage}\n";

    if ($result->billable) {
        echo "Charged: \$0.01\n";
    } else {
        echo "Not charged (system error)\n";
        // Safe to retry immediately
    }
}

Related Documentation

• Error Handling - HTTP status codes and common errors
• Error Handling Guide - Best practices and retry strategies
• Pricing - Render pricing and bundles
• Get Render - Full response format