Bright Data Web Unlocker Error Codes for AI Agents: Which Ones Are Worth a Retry, and What the Docs Say About Billing

Last fact-checked: November 17, 2026

Advertising disclosure: we may receive a commission if you sign up through the Bright Data † links marked † in this article, at no extra cost to you. We have not run production workloads on Bright Data; everything below comes from its official documentation. See our Advertising Disclosure.

Note on experience: we have not called the Web Unlocker API, triggered these errors or measured any bill. Pages were read on November 17, 2026 (the error-code page as raw page text, the other pages through a web-fetch tool that summarises them). Check the live docs before relying on any statement. "Not stated" means the page we read did not say.

An AI agent that calls Bright Data † Web Unlocker needs a rule for each failure: retry, change the request, or stop and tell a human. The vendor publishes an error-code page that sorts failures into exactly those groups. This article rewrites that page as an agent-oriented decision table and then lists what the docs do not tell you, mainly which failures are billed. For billing in general across vendors, see our article on what each vendor charges for failed scrapes; for retry caps, see our retry-budget article.

1. What the docs say about billing

The Web Unlocker overview says "You pay only for successful requests", and its FAQ answers "Do you pay for failed requests?" with no. The same page does not state a price, a pricing unit, a rate limit, or what counts as "successful". The error-code page, for its part, mentions billing once and only in another context: for feature_not_active it notes that custom features switch the zone to 100% billing. It does not say whether any individual error response is billed. So the headline promise exists, but the error table gives you no per-code billing detail.

2. Where to read the error

The error-code page says every Web Unlocker error carries an x-brd-error header with a message, and an x-brd-error-code header with a machine-readable code. In the Direct API, the outer response is 200 OK once the request reaches the unlocker, and the result is in x-brd-status-code. Proxy-level failures use x-brd-err-code and x-brd-err-msg, passed through from the proxy error catalog, and Proxy-Status appears on 400, 403 and 407 responses. The 502 unlock failures do not include Proxy-Status.

For an agent, this means the HTTP status alone is too coarse: a 502 can be a CAPTCHA that might clear on retry or a certificate problem that never will. Read x-brd-error-code first.

3. A decision table for agents

The page groups codes by whether a retry helps. Each retry uses a different peer, according to the page. The grouping below follows the page; the "agent action" column is our reading, not vendor guidance.

4. Timeouts and the 180-second note

For expect_element, the page says observed waits range from 30 to 150 seconds, so a client timeout shorter than that aborts the request before the error returns, and it advises allowing at least 180 seconds. It also says a URL that keeps returning this code keeps returning it, so report it to support with the req_id instead of retrying. If your agent framework uses a short tool timeout, this is a documented reason to check it for Web Unlocker calls. The related navigation_timeout code is described as a rendered page that did not finish navigating in time, and the page says to report a URL that times out consistently to support with the req_id; it does not place navigation_timeout or domcontentloaded_event_timeout in its retry table.

5. SERP API: a neighbouring product with thinner docs

The SERP API introduction says "Pay only for successful delivery" and lists 401/403 (check the API key and zone permissions) and 429 (reduce concurrency or switch to async). It gives no price, no definition of successful delivery, no numeric limits, and no error codes beyond those three. If an agent uses both products, do not assume the Web Unlocker error table applies to SERP requests.

6. A cautious checklist (our reading, not vendor guidance)

7. What we could not confirm

† Referral link (Bright Data). Related: Bright Data MCP preflight checklist, what you pay for failed scrapes, burst limits, retry budgets.

Sources (checked November 17, 2026)

Not sure which article you need? See the task-by-task chooser.