Bright Data Common Errors

Overview

Quick reference for the top 10 most common Bright Data errors and their solutions.

Prerequisites

• Bright Data SDK installed
• API credentials configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message and code in your logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Output

• Identified error cause
• Applied fix
• Verified resolution

Error Handling

Authentication Failed

Error Message:

Authentication error: Invalid API key

Cause: API key is missing, expired, or invalid.

Solution:

# Verify API key is set
echo $BRIGHTDATA_API_KEY

Rate Limit Exceeded

Error Message:

Rate limit exceeded. Please retry after X seconds.

Cause: Too many requests in a short period.

Solution:

Implement exponential backoff. See brightdata-rate-limits skill.

Network Timeout

Error Message:

Request timeout after 30000ms

Cause: Network connectivity or server latency issues.

Solution:

// Increase timeout
const client = new Client({ timeout: 60000 });

Examples

Quick Diagnostic Commands

# Check Bright Data status
curl -s https://status.brightdata.com

# Verify API connectivity
curl -I https://api.brightdata.com

# Check local configuration
env | grep BRIGHTDATA

Escalation Path

1. Collect evidence with brightdata-debug-bundle
2. Check Bright Data status page
3. Contact support with request ID

Resources

• Bright Data Status Page
• Bright Data Support
• Bright Data Error Codes

Next Steps

For comprehensive debugging, see brightdata-debug-bundle.

Bright Data Core Workflow A

Overview

Primary money-path workflow for Bright Data. This is the most common use case.

Prerequisites

• Completed brightdata-install-auth setup
• Understanding of Bright Data core concepts
• Valid API credentials configured

Instructions

Step 1: Initialize

// Step 1 implementation

Step 2: Execute

// Step 2 implementation

Step 3: Finalize

// Step 3 implementation

Output

• Completed Core Workflow A execution
• Expected results from Bright Data API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Common Variations

• Variation 1: Description
• Variation 2: Description

Resources

• Bright Data Documentation
• Bright Data API Reference

Next Steps

For secondary workflow, see brightdata-core-workflow-b.

Bright Data Core Workflow B

Overview

Secondary workflow for Bright Data. Complements the primary workflow.

Prerequisites

• Completed brightdata-install-auth setup
• Familiarity with brightdata-core-workflow-a
• Valid API credentials configured

Instructions

Step 1: Setup

// Step 1 implementation

Step 2: Process

// Step 2 implementation

Step 3: Complete

// Step 3 implementation

Output

• Completed Core Workflow B execution
• Results from Bright Data API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Error Recovery

// Error handling code

Resources

• Bright Data Documentation
• Bright Data API Reference

Next Steps

For common errors, see brightdata-common-errors.

Bright Data Cost Tuning

Overview

Optimize Bright Data costs through smart tier selection, sampling, and usage monitoring.

Prerequisites

• Access to Bright Data billing dashboard
• Understanding of current usage patterns
• Database for usage tracking (optional)
• Alerting system configured (optional)

Pricing Tiers

Cost Estimation

interface UsageEstimate {
  requestsPerMonth: number;
  tier: string;
  estimatedCost: number;
  recommendation?: string;
}

function estimateBright DataCost(requestsPerMonth: number): UsageEstimate {
  if (requestsPerMonth <= 1000) {
    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
  }

  if (requestsPerMonth <= 100000) {
    return { requestsPerMonth, tier: 'Pro', estimatedCost: 99 };
  }

  const proOverage = (requestsPerMonth - 100000) * 0.001;
  const proCost = 99 + proOverage;

  return {
    requestsPerMonth,
    tier: 'Pro (with overage)',
    estimatedCost: proCost,
    recommendation: proCost > 500
      ? 'Consider Enterprise tier for volume discounts'
      : undefined,
  };
}

Usage Monitoring

class Bright DataUsageMonitor {
  private requestCount = 0;
  private bytesTransferred = 0;
  private alertThreshold: number;

  constructor(monthlyBudget: number) {
    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
  }

  track(request: { bytes: number }) {
    this.requestCount++;
    this.bytesTransferred += request.bytes;

    if (this.estimatedCost() > this.alertThreshold) {
      this.sendAlert('Approaching Bright Data budget limit');
    }
  }

  estimatedCost(): number {
    return estimateBright DataCost(this.requestCount).estimatedCost;
  }

  private sendAlert(message: string) {
    // Send to Slack, email, PagerDuty, etc.
  }
}

Cost Reduction Strategies

Step 1: Request Sampling

function shouldSample(samplingRate = 0.1): boolean {
  return Math.random() < samplingRate;
}

// Use for non-critical telemetry
if (shouldSample(0.1)) { // 10% sample
  await brightdataClient.trackEvent(event);
}

Step 2: Batching Requests

// Instead of N individual calls
await Promise.all(ids.map(id => brightdataClient.get(id)));

// Use batch endpoint (1 call)
await brightdataClient.batchGet(ids);

Step 3: Caching (from P16)

• Cache frequently

Bright Data Debug Bundle

Overview

Collect all necessary diagnostic information for Bright Data support tickets.

Prerequisites

• Bright Data SDK installed
• Access to application logs
• Permission to collect environment info

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# brightdata-debug-bundle.sh

BUNDLE_DIR="brightdata-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Bright Data Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment Info

# Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "BRIGHTDATA_API_KEY: ${BRIGHTDATA_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 3: Gather SDK and Logs

# SDK version
npm list @brightdata/sdk 2>/dev/null >> "$BUNDLE_DIR/summary.txt"

# Recent logs (redacted)
grep -i "brightdata" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"

# Configuration (redacted - secrets masked)
echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
cat .env 2>/dev/null | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE_DIR/config-redacted.txt"

# Network connectivity test
echo "--- Network Test ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "API Health: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code}" https://api.brightdata.com/health >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 4: Package Bundle

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Output

• brightdata-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
• summary.txt - Environment and SDK info
• logs.txt - Recent redacted logs
• config-redacted.txt - Configuration (secrets removed)

Error Handling

# Add Bright Data secrets to Vercel
vercel secrets add brightdata_api_key sk_live_***
vercel secrets add brightdata_webhook_secret whsec_***

# Link to project
vercel link

# Deploy preview
vercel

# Deploy production
vercel --prod

{
  "env": {
    "BRIGHTDATA_API_KEY": "@brightdata_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

app = "my-brightdata-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

# Set Bright Data secrets
fly secrets set BRIGHTDATA_API_KEY=sk_live_***
fly secrets set BRIGHTDATA_WEBHOOK_SECRET=whsec_***

# Deploy
fly deploy

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]

#!/bin/bash
# deploy-cloud-run.sh

PROJECT_ID="${GOOGLE_CLOUD_PROJECT}"
SERVICE_NAME="brightdata-service"
REGION="us-central1"

# Build and push image
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME

# Deploy to Cloud Run
gcloud run deploy $SERVICE_NAME \
  --image gcr.io/$PROJECT_ID/$SERVICE_NAME \
  --region $REGION \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets=BRIGHTDATA_API_KEY=brightdata-api-key:latest

// config/brightdata.ts
interface Bright DataConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  webhookSecret?: string;
}

export function getBright DataConfig(): Bright DataConfig {
  const env = process.env.NODE_ENV || 'development';

  return {
    apiKey: process.env.BRIGHTDATA_API_KEY!,
    environment: env as Bright DataConfig['environment'],
    webhookSecret: process.env.BRIGHTDATA_WEBHOOK_SECRET,
  };
}

// api/health.ts
export async function GET() {
  const br

import { BrightDataClient } from '@brightdata/sdk';

const client = new BrightDataClient({
  apiKey: process.env.BRIGHTDATA_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

Success! Your Bright Data connection is working.

import { BrightDataClient } from '@brightdata/sdk';

const client = new BrightDataClient({
  apiKey: process.env.BRIGHTDATA_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

from brightdata import BrightDataClient

client = BrightDataClient()

# Your first API call here

# Node.js
npm install @brightdata/sdk

# Python
pip install brightdata

# Set environment variable
export BRIGHTDATA_API_KEY="your-api-key"

# Or create .env file
echo 'BRIGHTDATA_API_KEY=your-api-key' >> .env

// Test connection code here

import { BrightDataClient } from '@brightdata/sdk';

const client = new BrightDataClient({
  apiKey: process.env.BRIGHTDATA_API_KEY,
});

from brightdata import BrightDataClient

client = BrightDataClient(
    api_key=os.environ.get('BRIGHTDATA_API_KEY')
)

my-brightdata-project/
├── src/
│   ├── brightdata/
│   │   ├── client.ts       # Bright Data client wrapper
│   │   ├── config.ts       # Configuration management
│   │   └── utils.ts        # Helper functions
│   └── index.ts
├── tests/
│   └── brightdata.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
└── package.json

# Copy environment template
cp .env.example .env.local

# Install dependencies
npm install

# Start development server
npm run dev

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

import { describe, it, expect, vi } from 'vitest';
import { BrightDataClient } from '../src/brightdata/client';

describe('Bright Data Client', () => {
  it('should initialize with API key', () => {
    const client = new BrightDataClient({ apiKey: 'test-key' });
    expect(client).toBeDefined();
  });
});

vi.mock('@brightdata/sdk', () => ({
  BrightDataClient: vi.fn().mockImplementation(() => ({
    // Mock methods here
  })),
}));

# Enable verbose logging
DEBUG=BRIGHTDATA=* npm run dev

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedBright DataRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

import DataLoader from 'dataloader';

const brightdataLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from Bright Data
    const results = await brightdataClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  brightdataLoader.load('id-1'),
  brightdataLoader.load('id-2'),
  brightdataLoader.load('id-3'),
]);

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new BrightDataClient({
  apiKey: process.env.BRIGHTDATA_API_KEY!,
  httpAgent: agent,
});

async function* paginatedBright DataList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nex

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.brightdata.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/brightdata-integration app=image:new --record
kubectl rollout pause deployment/brightdata-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/brightdata-integration
kubectl rollout pause deployment/brightdata-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/brightdata-integration
kubectl rollout status deployment/brightdata-integration

async function healthCheck(): Promise<{ st

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: BrightDataClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

my-brightdata-project/
├── src/
│   ├── brightdata/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── brightdata/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── brightdata/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── brightdata/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── brightdata/
│   └── integration/
│       └── brightdata/
├── config/
│   ├── brightdata.development.json
│   ├── brightdata.staging.json
│   └── brightdata.production.json
└── docs/
    └── brightdata/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          Bright Data Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/brightdata/client.ts
export class Bright DataService {
  private client: BrightDataClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: Bright DataConfig) {
    this.client = new BrightDataClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('brightdata');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/brightdata/errors.ts
export class Bright DataServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
 

// src/brightdata/client.ts
import { BrightDataClient } from '@brightdata/sdk';

let instance: BrightDataClient | null = null;

export function getBright DataClient(): BrightDataClient {
  if (!instance) {
    instance = new BrightDataClient({
      apiKey: process.env.BRIGHTDATA_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { Bright DataError } from '@brightdata/sdk';

async function safeBright DataCall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof Bright DataError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, BrightDataClient>();

export function getClientForTenant(tenantId: string): BrightDataClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenan

# .env (NEVER commit to git)
BRIGHTDATA_API_KEY=sk_live_***
BRIGHTDATA_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

# 1. Generate new key in Bright Data dashboard
# 2. Update environment variable
export BRIGHTDATA_API_KEY="new_key_here"

# 3. Verify new key works
curl -H "Authorization: Bearer ${BRIGHTDATA_API_KEY}" \
  https://api.brightdata.com/health

# 4. Revoke old key in dashboard

const clients = {
  reader: new BrightDataClient({
    apiKey: process.env.BRIGHTDATA_READ_KEY,
  }),
  writer: new BrightDataClient({
    apiKey: process.env.BRIGHTDATA_WRITE_KEY,
  }),
};

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'su

npm list @brightdata/sdk
npm view @brightdata/sdk version

open https://github.com/brightdata/sdk/releases

git checkout -b upgrade/brightdata-sdk-vX.Y.Z
npm install @brightdata/sdk@latest
npm test

// Before (v1.x)
import { Client } from '@brightdata/sdk';

// After (v2.x)
import { BrightDataClient } from '@brightdata/sdk';

// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new BrightDataClient({
  apiKey: 'xxx',
});

npm install @brightdata/sdk@1.x.x --save-exact

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Bright Data]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/brightdata',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-brightdata-signature'] as string;
    const timestamp = req.headers['x-brightdata-timestamp'] as string;

    if (!verifyBright DataSignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleBright DataEvent(event);

    res.status(200).json({ received: true });
  }
);

function verifyBright DataSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.BRIGHTDATA_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

type Bright DataEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface Bright DataEvent {
  id: string;
  type: Bright DataEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<Bright DataEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handleBright DataEvent(event: Bright DataEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.