Originally published at AgentStack Notes. Last fact-checked: November 17, 2026.
Disclosure: This article was drafted with AI assistance and checked against Bright Data's official documentation. We may receive a commission if you sign up through the links marked † in this article (Bright Data †), at no extra cost to you. We have not run production workloads on Bright Data; everything below comes from its official documentation.
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.
A 502 from Bright Data † Web Unlocker can be a CAPTCHA that may clear on a second try, or a certificate problem that will fail every time, and the HTTP status alone does not tell you which. Bright Data's error-code page separates them, so this post turns that page into a retry / change-the-request / stop table and then lists what the docs leave unstated, chiefly which failures are billed.
1. Billing: one promise, no per-code detail
The Web Unlocker overview says "You pay only for successful requests", and its FAQ answers "Do you pay for failed requests?" with no. It does not state a price, a pricing unit, a rate limit, or what counts as "successful". The error-code page mentions billing once, in another context: feature_not_active notes that custom features switch the zone to 100% billing. It does not say whether any individual error response is billed.
2. Read the code, not the HTTP status
Every Web Unlocker error carries an x-brd-error header (message) and an x-brd-error-code header (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. A 502 can be a CAPTCHA that may clear on retry or a certificate problem that never will, so branch on x-brd-error-code.
3. Decision table
The grouping follows the docs; the agent actions are our reading, not vendor guidance.
-
Retry can succeed:
reject_block(CAPTCHA or protection page detected; the page says the same request has been seen to succeed later) andresolve_failed_*. Retry within a small fixed budget. -
One attempt is worth it:
http_status(the target returned a blocking status, including a 429 from the target). If it persists, contact support with thereq_id. -
Same error every time: certificate errors (
net_err_cert_*),document_load_failedfrom a TLS or cipher mismatch,proxy_errorwhen the host does not resolve, andno_peers(no available peers for the requested country). Stop; forno_peers, change or drop the country. -
Configuration errors (HTTP 400, no unlock attempted):
premium,feature_not_active,ub_bad_endpoint_robots. Surface to a human. -
Auth and zone errors: 401 (API key, Direct API), 403 with
policy_20020orclient_10090, and 407 withclient_10000,client_10002,client_10010orclient_10001. These are setup bugs, not transient faults. -
Compliance policy (non-retryable): 403 with
policy_20051orpolicy_20000(government sites and a blocked domain classification, per the KYC page). Stop and surface to a human; we suggest no workaround. -
Throttling:
sr_rate_limit(429) means the health monitor throttled requests to this target; the docs say to contact support and give no back-off interval. The 502rate_limitcode is a different, Bright Data-side limit.
On robots.txt: the Web Unlocker KYC page (read November 18) says new accounts start in "immediate access mode", which honours the target's robots.txt; disallowed endpoints open only after KYC approval. Treat these denials as non-retryable; the 403 reading is ours, not vendor guidance.
4. The 180-second note
For expect_element, the page says observed waits run from 30 to 150 seconds and advises allowing at least 180 seconds, so a shorter client timeout can abort the call before the error returns. If your agent framework uses a short tool timeout, check it for Web Unlocker calls.
5. SERP API has thinner docs
The SERP API introduction says "Pay only for successful delivery" and lists 401/403 and 429 only. It gives no price, no definition of successful delivery and no numeric limits. Do not assume the Web Unlocker error table applies to SERP requests.
6. Checklist (our reading)
- Log
x-brd-error-code,x-brd-errorand thereq_idfor every failed call. - 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.
- Use client timeouts of at least 180 seconds for calls that may hit
expect_element. - Compare your first invoice with the number of successes you recorded; the docs give no per-error billing table.
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 pages we read.
- A back-off interval for
sr_rate_limit, and numeric rate or concurrency limits. - Whether the error table is complete for SERP API zones.
- How KYC approval is decided, and which categories count as in or out of an approved use case.
Sources: docs.brightdata.com (Web Unlocker API introduction; Web Unlocker API error codes; SERP API introduction; Web Unlocker API and KYC). Checked November 17-18, 2026.
More: the original article, and our earlier pieces on failed-scrape billing and retry budgets.
Top comments (0)