brightdata-common-errors

# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```typescript
// 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:

| 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

```bash
# Check Bright Data status
curl -s https://status.brightdata.com/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 https://status.brightdata.com for outages
4. Contact support with zone name, error headers, and timestamps

## Resources

- [Bright Data Error Reference](https://docs.brightdata.com/general/account/troubleshooting)
- [Status Page](https://status.brightdata.com)
- [Support Portal](https://brightdata.com/cp/support)

## Next Steps

For comprehensive debugging, see `brightdata-debug-bundle`.