Brightdata Proxy

Residential & Mobile network access

Residential and Mobile have a network access policy that Datacenter and ISP don't. The user must pick one of these three before requests will succeed against arbitrary HTTPS targets:

1. Use the Bright Data CA certificate (preferred — what most users should do). The cert is already bundled in this skill at assets/brightdata_proxy_ca.crt. Two ways to apply it:
   • Load it in code for each request (no system install needed). For Python requests: verify="./assets/brightdata_proxy_ca.crt". For cURL: --cacert ./assets/brightdata_proxy_ca.crt. For Node: set NODE_EXTRA_CA_CERTS=./assets/brightdata_proxy_ca.crt env var or pass a custom Agent with ca. This is the cleanest path and what we recommend by default in generated code.
   • System-install the cert (Windows / macOS Keychain / Linux update-ca-certificates / iOS / Android). Needed when using third-party tools that don't expose a CA-cert option. Copy the bundled assets/brightdata_proxy_ca.crt to the appropriate trust store, restart the app afterward. Public mirror at https://brightdata.com/static/brightdata_proxy_ca.zip if the user prefers to grab it independently.
2. KYC verification. Submit identity verification in the Bright Data control panel. After approval, the cert is no longer required for native proxy access.
3. Ignore SSL errors (last resort, not recommended for production). In Python: requests.get(..., verify=False). In Node: rejectUnauthorized: false or NODE_TLS_REJECT_UNAUTHORIZED=0. In cURL: -k. This works but loses end-to-end encryption guarantees against MITM — fine for throwaway testing, bad for anything handling credentials or PII.

Generated code for Residential/Mobile should default to path 1a (load CA in code) with the cert path as a placeholder the user fills in. Mention path 2 and 3 as alternatives, briefly.

For Datacenter and ISP, none of this is required — they don't enforce the network access policy.

Testing & debugging

Before scraping a real target, confirm the proxy works. Two bundled tools cover this end-to-end:

1. Command-line smoke test — scripts/smoke_test.sh:

./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD
# with optional country and sticky session:
./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD us my-session-1

# or via env vars:
BD_CUSTOMER_ID=xxx BD_ZONE=yyy BD_PASSWORD=zzz ./scripts/smoke_test.sh

It hits geo.brdtest.com/mygeo.json through the zone and returns the parsed JSON (IP, country, city, ASN). Exit codes distinguish auth failure (2) from HTTP error (3), so it's also fine to script around.

2. Browser diagnostic — scripts/proxy_tester.html:

Open the file in a browser. It continuously polls the geo endpoint and displays exit IP/country/city/ASN. Fill in your zone credentials and it generates the exact proxy config string to paste into your browser or OS proxy settings. The "Save as baseline" button captures your pre-proxy IP so you can visually confirm the proxy is active (the status flips to green and shows the before→after change). Useful when explaining to teammates that the proxy is working, or for debugging "is my browser actually going through the proxy" questions.

For ad-hoc one-liners, the raw cURL works too:

curl --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  --cacert ./assets/brightdata_proxy_ca.crt \
  'https://geo.brdtest.com/mygeo.json'

Expected: JSON with ip, country, asn, geo. If you see this, auth and routing are working. Do not test against Google, Bing, or other search engines directly — Bright Data blocks direct search-engine access on the proxy networks. Use the SERP API for that.

Common errors and what they mean (high-signal subset):

• 407 Proxy Authentication Required: wrong username structure or wrong zone password. Double-check brd-customer- prefix and -zone- segment. The customer ID is from the control panel, not your email.
• 502 "no peer available": usually from -const or -ip- to an IP that's offline. Drop -const or pick a different IP.
• 403 from the destination (not from Bright Data): the destination blocked the proxy IP. Try Residential, add a sticky session, slow down request rate, or use Web Unlocker API.
• TLS / certificate errors on Residential/Mobile: you skipped the network-access setup. Install the cert (or load it in code), or fall back to verify=False for the moment.
• Targeting silently ignored on DC/ISP: you used -city- or -state- on a DC/ISP zone. They only honor -country-.

For any specific Bright Data error code not covered above, look it up in the full catalog: https://docs.brightdata.com/proxy-networks/errorCatalog. Inspect the response headers for the precise code — Bright Data is transitioning from the legacy x-brd-err-code header to the RFC 9209 standard Proxy-Status header, so generated debugging code should check both. Codes follow a category_number shape that tells you which layer failed at a glance: client_* (auth or request shape, e.g. client_10000), policy_* (Bright Data policy block, e.g. policy_20050), target_* (destination-side failure, e.g. target_40011), and the like.

When the user hasn't set up a zone yet

Don't try to script the control-panel flow or call account-management APIs to create zones for them — those flows are interactive and account-specific. Instead, say:

Sign up at https://brightdata.com (new accounts get $2 trial credit for 7 days, plus a $5 bonus for 30 days after adding a payment method — note proxy products are billed separately and are not covered by the monthly free credits). Once you're in, click Proxies & Scraping → Add and the in-app helper will walk you through choosing the network, the pool type, and naming the zone. When it finishes, copy the customer ID, zone name, and zone password from the zone's overview page and paste them in here — I'll generate the code.

The control panel's proxy_examples page (https://brightdata.com/cp/zones/proxy_examples) also has live, account-specific snippets for many languages and frameworks — use it as a sanity check if anything in this skill seems out of date.

Reference files

• references/code-templates.md — full working code for Playwright, Puppeteer, Selenium (modern auth-extension approach + SeleniumWire fallback), Scrapy, httpx, aiohttp, and a few language variants. Read this when the user asks about a specific framework that isn't covered above.
• references/troubleshooting.md — extended error catalog and debugging recipes. Read when the user reports an error or unexpected behavior.
• assets/brightdata_proxy_ca.crt — Bright Data Proxy Root CA (port 33335, expires Sept 2034). Reference this path in any generated code that uses Residential or Mobile zones.
• scripts/smoke_test.sh — cURL credential smoke test (see Testing section).
• scripts/proxy_tester.html — single-file browser diagnostic (see Testing section).