Bright Data Common Errors
Overview
Diagnostic reference for the most common Bright Data proxy and API errors with real solutions and fix commands.
Prerequisites
- Bright Data zone configured
- Proxy credentials available
- Access to error logs
Instructions
Step 1: Identify the Error
Check your proxy response status code or error message against the table below.
Step 2: Apply the Fix
Follow the specific solution for your error code.
Error Reference
407 Proxy Authentication Required
HTTP/1.1 407 Proxy Authentication Required
Cause: Username format is wrong or credentials are invalid.
Fix:
echo "Username: brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}"
curl -x "http://brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
https://lumtest.com/myip.json
502 Bad Gateway
HTTP/1.1 502 Bad Gateway
X-Luminati-Error: target_site_blocked
Cause: Target site blocked the request despite Web Unlocker retries.
Fix:
- Increase timeout to 120s (Web Unlocker needs time to solve CAPTCHAs)
- Switch to Scraping Browser zone for JS-heavy sites
- Add
-country-us to username for geo-specific content
SSL Certificate Errors
Error: SSL: CERTIFICATE_VERIFY_FAILED
Cause: Missing Bright Data CA certificate for HTTPS proxying.
Fix:
curl -sO https://brightdata.com/ssl/brd-ca.crt
export NODE_EXTRA_CA_CERTS=./brd-ca.crt
ETIMEDOUT / Connection Timeout
Error: connect ETIMEDOUT brd.superproxy.io:33335
Cause: Firewall blocking outbound connections to Bright Data.
Fix:
nc -zv brd.superproxy.io 33335
nc -zv brd.superproxy.io 9222
403 Forbidden (Zone Inactive)
Cause: Zone is not active or has been paused.
Fix: Go to https://brightdata.com/cp, navigate to the zone, and click "Activate".
429 Too Many Requests
Cause: Exceeded concurrent request limit for your zone.
Fix:
import PQueue from 'p-queue';
const queue = new PQueue({ concurrency: 10, interval: 1000, intervalCap: 20 });
const result = await queue.add(() => client.get(url));
Empty Response Body
Cause: Target returned a CAPTCHA page that Web Unlocker couldn't solve, or wrong zone type for the target.
Fix:
- Check zone type matches target (Web Unlocker for static, Scraping Browser for JS)
- Verify target URL is accessible in a regular browser
- Try adding
&brd_json=1 for SERP API requests
X-Luminati-Error Headers
Bright Data returns error details in response headers:
| Header Value | Meaning | Action |
|---|
target_site_blocked | Site anti-bot blocked request | Use Scraping Browser |
ip_banned | IP was banned by target | Retry (auto-rotates IP) |
captcha | CAPTCHA challenge failed | Increase timeout |
connection_failed | Could not reach target | Verify target URL |
auth_failed | Credential error | Check username/password |
Quick Diagnostic Commands
curl -s api/v2/status.json | python3 -m json.tool
curl -x "http://brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
-o /dev/null -s -w "HTTP %{http_code} in %{time_total}s\n" \
https://lumtest.com/myip.json
curl -H "Authorization: Bearer ${BRIGHTDATA_API_TOKEN}" \
https://api.brightdata.com/zone/get_active_zones
Escalation Path
- Collect request/response headers (including
X-Luminati-* headers)
- Run
brightdata-debug-bundle to create diagnostic package
- Check for outages
- Contact support with zone name, error headers, and timestamps
Resources
Next Steps
For comprehensive debugging, see brightdata-debug-bundle.
