Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/brightdata-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill brightdata-common-errors. Copyright stays with the author (MIT).

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:

# Verify credential format — must be exactly:
# brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}
echo "Username: brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}"

# Test with curl
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:

# Download the Bright Data CA certificate
curl -sO https://brightdata.com/ssl/brd-ca.crt

# Node.js
export NODE_EXTRA_CA_CERTS=./brd-ca.crt

# Python requests
# requests.get(url, proxies=proxies, verify='./brd-ca.crt')

ETIMEDOUT / Connection Timeout

Error: connect ETIMEDOUT brd.superproxy.io:33335

Cause: Firewall blocking outbound connections to Bright Data.

Fix:

# Test connectivity
nc -zv brd.superproxy.io 33335
# If blocked, allow outbound TCP to brd.superproxy.io:33335

# For Scraping Browser, also allow port 9222
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:

// Implement request queuing
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:

Quick Diagnostic Commands

# Check Bright Data status
curl -s api/v2/status.json | python3 -m json.tool

# Test proxy connectivity
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

# Check zone credentials
curl -H "Authorization: Bearer ${BRIGHTDATA_API_TOKEN}" \
  https://api.brightdata.com/zone/get_active_zones

Escalation Path

1. Collect request/response headers (including X-Luminati-* headers)
2. Run brightdata-debug-bundle to create diagnostic package
3. Check for outages
4. Contact support with zone name, error headers, and timestamps

Output

Troubleshooting produces a redacted error category, request identifier, policy/authorization state, retry decision, and escalation owner. It excludes proxy credentials, full URLs with parameters, raw response bodies, and target data.

Error Handling

Retry only explicitly transient, idempotent operations within the approved rate and cost budget. Pause on authorization, compliance, unexpected-data, or persistent block failures; preserve a redacted receipt and escalate to the designated owner rather than rotating proxies or changing collection behavior to evade controls.

Examples

For a timeout, retry one idempotent test request after bounded backoff and record the request identifier. For a 401/403 or policy block, stop, verify the authorized zone/credential and target scope, and obtain approval before resuming—do not treat an access denial as a signal to bypass controls.

Resources

• Bright Data Error Reference
• Status Page
• Support Portal

Next Steps

For comprehensive debugging, see brightdata-debug-bundle.