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
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.
- Retry can succeed:
reject_block(a CAPTCHA or protection page was detected; the page says the same request has been observed to succeed on a later attempt) andresolve_failed_*(a CAPTCHA solve was attempted and did not complete). Agent action: retry within a small, fixed budget. - Retry is worth one attempt:
http_status(the target returned a blocking status, which also covers a 429 from the target site itself). If it persists, the page says the target is blocking the current setup and you should contact support with thereq_id. - Same error every time, fix the cause:
net_err_cert_date_invalid,net_err_cert_common_name_invalid,net_err_cert_authority_invalid(target certificate problems),document_load_failedwhen the cause is a TLS or cipher mismatch,proxy_errorwhen the host does not resolve (the page says retrying does not help "despite what the message says"), andno_peers(returned for every request that targets a country with no available peers, including valid ISO codes). Agent action: stop, do not loop; forno_peers, change or drop the country parameter. - Configuration errors (HTTP 400, no unlock attempt made):
premium(enable Premium domains on the zone),feature_not_active(a custom feature such as thex-unblock-expectheader is not enabled on the zone) andub_bad_endpoint_robots(the path is disallowed by robots.txt in immediate access mode; the page says to ask your account manager for full access). Agent action: surface to a human; the result does not change until the zone or request changes. - Auth and zone errors: 401 for API key problems in the Direct API; 403 with
policy_20020(unsupported destination port) orclient_10090(a Browser API zone cannot use this interface); 407 withclient_10000(wrong zone password or customer ID),client_10002(zone not found),client_10010(no credentials sent) orclient_10001(malformed username parameters). Agent action: stop; these are setup bugs, not transient faults. - Throttling:
sr_rate_limit(429): the page says Bright Data's health monitor throttled requests to this target after the success rate dropped, and tells you to contact support. It does not give a back-off interval. The 502rate_limitcode is a different thing: a Bright Data-side limit hit while opening the connection.
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)
- Log
x-brd-error-code,x-brd-errorand thereq_idfor every failed call; the page tells you to include thereq_idwhen reporting a URL to support. - Branch on the code, not on the HTTP status.
- Give
reject_blockandresolve_failed_*a small fixed retry budget; do not retry certificate,no_peers, 400 or auth errors. - Treat 400s as human-fix items: they change only when the zone or request changes.
- Set client timeouts of at least 180 seconds for calls that may hit
expect_element. - Check your first invoice against the number of successes you recorded, since the docs give no per-error billing table.
7. What we could not confirm
- Whether any error response (400, 401, 403, 407, 429, 502 or 503) is billed.
- Whether retries after errors are billed.
- What "successful" means for billing, for example whether a 200 with a block page counts.
- Prices, pricing units, free tiers and refunds on the Web Unlocker pages we read.
- A back-off interval for
sr_rate_limit. - Numeric rate or concurrency limits.
- Whether the error table is complete for SERP API zones.
† 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.