Errors
This section covers errors encountered when interacting directly with Bright Data’s Unlocker, SERP API, Web Scraper API, Marketplace Dataset API, and Web Scraper IDE.
API errors
200 ok (with error/status messages)
While technically a successful HTTP status, these responses carry messages indicating an ongoing process or a specific failure within the operation, requiring developer attention.
| Message | Associated endpoints | Cause | Suggested action |
|---|---|---|---|
{status: "STATUS", message: "Snapshot is not ready yet, try again in 10s"} | GET /datasets/v3/snapshot/:snapshot_id | The snapshot is still being built or processed. | This is an interim status. Poll the endpoint again after the suggested delay (e.g., 10s). |
{status: "building", message: "Snapshot is building, try again in 10s"} | GET /datasets/v3/snapshot/:snapshot_id | The snapshot is actively being built. | Poll the endpoint again after the suggested delay. |
{status: "failed", error_message: "ERROR_MESSAGE"} | GET /datasets/v3/progress/:snapshot_id | A collection or snapshot operation has failed. | Check the specific ERROR_MESSAGE for details. Review your collection setup and inputs. |
Something went wrong. Our team is looking into it. | GET /datasets/v3/progress/:snapshot_id | An internal system error occurred during monitoring. | This indicates a problem on Bright Data’s end. No immediate action is required from your side, but you can contact support if it persists. |
Account is suspended | GET /datasets/v3/progress/:snapshot_id | Your Bright Data account has been suspended, often due to a negative balance. | Top up your account balance. If suspension extends beyond 24 hours, previously allocated static IPs may be released. Go to your Bright Data Zones page for updated IPs. |
Account is new, please activate it in account settings. URL | GET /datasets/v3/progress/:snapshot_id | Your newly created account requires activation. | Log in to your Bright Data account settings and complete the activation process. |
No data found in discovery | GET /datasets/v3/progress/:snapshot_id | The discovery phase of your collection did not yield any data. | Review your discovery configuration and target settings. |
Snapshot is empty | GET /datasets/v3/progress/:snapshot_id | The completed snapshot contains no data. | Check your collection process and dataset configuration to ensure data is being collected. |
Failed to deliver snapshot | GET /datasets/v3/progress/:snapshot_id | An error occurred during the process of delivering the collected data to storage. | Review your delivery options and try again. If the issue persists, contact support. |
Failed to download response | GET /datasets/v3/progress/:snapshot_id | An error occurred while attempting to download the response. | This could be a transient network issue or a problem on Bright Data’s side. Retry the request. |
Failed to trigger collector | GET /datasets/v3/progress/:snapshot_id | An internal error prevented the collection from being triggered. | Retry the request. If the issue persists, contact support. |
Internal server error | GET /datasets/v3/progress/:snapshot_id | A general internal server error. | Retry the request. If the issue persists, contact support. |
Input validation failed: DETAILS | GET /datasets/v3/progress/:snapshot_id | There was an internal validation error with the input. | Review your input against the API documentation. If it appears correct, contact support. |
202 accepted
Cause: The request has been accepted for processing, but the operation is not yet complete. This is typically an interim status indicating that a resource is being prepared or built.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
{status: "STATUS", message: "Snapshot is not ready yet, try again in 10s"} | GET /datasets/v3/snapshot/:snapshot_id | The snapshot is still being built or processed. | This is an interim status. Poll the endpoint again after the suggested delay (e.g., 10s). |
{status: "building", message: "Snapshot is building, try again in 10s"} | GET /datasets/v3/snapshot/:snapshot_id | The snapshot is actively being built. | Poll the endpoint again after the suggested delay. |
400 bad request
Cause: Your request was invalid, malformed, or contained incorrect parameters. This is a common client-side error, indicating an issue with how the request was constructed.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
{validation_errors: [ERRORS]} | Many Scrapers Library endpoints, GET /datasets/v3/snapshots, Marketplace Dataset API | General validation failure for request inputs; the ERRORS array will provide specific details. | Check the ERRORS array for specific validation issues and correct your request payload. |
dataset missing | POST /datasets/v3/trigger | The required dataset ID or name is missing from the request. | Ensure the dataset identifier is included in your request. |
Invalid attachments | POST /datasets/v3/trigger | The attachments provided are not valid. | Verify the format and content of your attachments. |
This dataset is not allowed for API | POST /datasets/v3/trigger | The specified dataset cannot be triggered via API. | Confirm that the dataset is configured for API access. |
This dataset is not ready yet | POST /datasets/v3/trigger | The dataset is still being prepared or is not in an active state. | Wait for the dataset to become ready before attempting to trigger a collection. |
No data to trigger | POST /datasets/v3/trigger | The dataset has no inputs or configuration to initiate a collection. | Ensure your dataset has valid inputs defined. |
Should be at least LIMIT inputs | POST /datasets/v3/trigger | The request does not meet the minimum number of required inputs. | Provide at least the specified LIMIT number of inputs. |
Snapshot is expired | GET /datasets/v3/snapshot/:snapshot_id, POST /datasets/v3/deliver/:snapshot_id | The snapshot you are trying to access has passed its validity period. | Trigger a new collection to generate a fresh snapshot. |
Snapshot is empty | GET /datasets/v3/snapshot/:snapshot_id, POST /datasets/v3/deliver/:snapshot_id | The collected snapshot contains no data. | Check your collection process and dataset configuration to ensure data is being collected. |
Snapshot is not ready | GET /datasets/v3/snapshot/:snapshot_id/parts, POST /datasets/v3/deliver/:snapshot_id | The snapshot is still being processed or is not in a state to be downloaded or delivered. | Wait for the snapshot to complete processing. You can monitor its status via the “Monitor progress” endpoint. |
Snapshot input does not exist | GET /datasets/v3/snapshot/:snapshot_id/input | The input file associated with the snapshot could not be found. | Verify the snapshot_id and ensure the input file was successfully generated. |
Snapshot is not running | POST /datasets/v3/snapshot/:snapshot_id/cancel | You attempted to cancel a collection that is not currently active. | Check the status of the collection before attempting to cancel it. |
Deliver options are missing | POST /datasets/v3/deliver/:snapshot_id | Required delivery configuration (e.g., destination details) was not provided. | Ensure all necessary delivery options are included in your request. |
Snapshot is too big for single file delivery | POST /datasets/v3/deliver/:snapshot_id | The collected data exceeds the limit for a single file delivery. | Consider delivering the snapshot in multiple parts or adjusting your collection scope. |
Batch size should be at least MIN_BATCH_SIZE | POST /datasets/v3/deliver/:snapshot_id | The specified batch size for delivery is below the minimum allowed. | Increase the batch_size to at least MIN_BATCH_SIZE. |
Type <span class="math-inline">\{init\_types\.compr\_update is no longer supported\. Use '</span>{init_types.discover_all}' instead. | Marketplace Dataset API | The requested operation type is deprecated. | Update your request to use the recommended operation type, ${init_types.discover_all}. |
Type ${init_types.update_existing} is no longer supported. | Marketplace Dataset API | The requested operation type is no longer supported. | Use a supported operation type. |
Type ${init_types.discover_new} is no longer supported. | Marketplace Dataset API | The requested operation type is no longer supported. | Use a supported operation type. |
Initiation reason is required. | Marketplace Dataset API | The request is missing the required initiation reason. | Include the initiation reason in your request. |
This feature is not available. | Marketplace Dataset API | The requested feature is not supported for the dataset. | Check the dataset’s capabilities and adjust your request accordingly. |
This dataset was rejected. | Marketplace Dataset API | The dataset was rejected and cannot be processed. | This dataset cannot be used. Contact Bright Data support for more information. |
This dataset is not ready. | Marketplace Dataset API | The dataset is not in a state where it can be processed. | Wait for the dataset to become ready. |
This dataset does not support discovery. Supported types: ['${init_types.url_collection}'] | Marketplace Dataset API | The dataset does not support the requested discovery type. | Use a supported discovery type, such as url_collection. |
Incorrect discovery collector id. | Marketplace Dataset API | The discovery collector ID provided in the request is invalid. | Verify the discovery collector ID. |
View not found. | Marketplace Dataset API | The requested view is not available. | Check for correct view names and available views for the dataset. |
This dataset does not support collection. | Marketplace Dataset API | The dataset does not support the requested collection operation. | Use an operation supported by the dataset. |
Batch size must be at least 1000. | Marketplace Dataset API | The batch size specified in the request is below the minimum allowed value. | Increase the batch_size to at least 1000. |
{error: 'Snapshot failed'} | Marketplace Dataset API | The snapshot operation failed. | Review the collection process for underlying issues. |
{error: 'Invalid snapshot type'} | Marketplace Dataset API | The snapshot type provided in the request is invalid. | Use a valid snapshot type. |
401 unauthorized
Cause: Your request lacks valid authentication credentials for the API.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
Unauthorized | Marketplace Dataset API | The API key or authentication credentials provided are invalid or missing. | Ensure your API key and authentication credentials are correct and properly included in the request. |
402 payment required
Cause: Your account balance is insufficient to process the requested API operation.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
{error: 'Your current balance is insufficient to process this data collection request. Please add funds to your account or adjust your request to continue. ($220 is missing)'} | Marketplace Dataset API | The user’s account balance is insufficient to process the request. | Add funds to your Bright Data account or adjust your request parameters to reduce its cost. |
403 forbidden
Cause: You do not have permission to access the requested API resource, or your request is being blocked by a Bright Data policy.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
Access denied. | Marketplace Dataset API | The user does not have the necessary permissions to access the resource. | Check your account permissions and ensure you have access to the requested resource. |
Cannot skip billing. | Marketplace Dataset API | The user attempted to skip billing, which is not allowed. | Billing |
404 not found
Cause: The specific API resource you’re trying to access does not exist in the system. You may encounter this error when trying to access a dataset, snapshot, delivery, or a general request that isn’t found.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
dataset does not exist | POST /datasets/v3/trigger, Marketplace Dataset API | The specified dataset ID or name could not be found. | Double-check the dataset identifier in your request. |
Snapshot does not exist | Many scrapers endpoints, Marketplace Dataset API | The snapshot_id provided does not correspond to an existing snapshot. | Verify the snapshot_id. It might be incorrect, expired, or never existed. |
Delivery does not exist | GET /datasets/v3/delivery/:delivery_id | The delivery_id provided could not be found. | Confirm the delivery_id is correct. |
Request not found. | Web Scraper IDE API, Marketplace Dataset API | The specified request ID or other request details were not found in our system. | Verify your request details and ensure they are valid. |
Page not found. | Invalid URL, which suggests the URL might be broken or dead (specific to Web Unlocker). | Verify the URL is correct and active. |
422 unprocessable entity
Cause: The API request was well-formed but could not be processed due to semantic errors in the data provided.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
{error: 'Provided filter did not match any records'} | Marketplace Dataset API | The filter provided in the request did not match any records in the dataset. | Adjust your filter criteria to match existing records in the dataset. |
429 too many requests
Cause: You have exceeded a rate limit or the maximum number of parallel jobs allowed for your account or dataset when using the API.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
You have too many running jobs for this dataset. | POST /datasets/v3/trigger | You’ve hit the concurrency limit for collection jobs on this dataset. | Wait for some active jobs to complete. For large workloads, consider combining multiple inputs into a single collection request to reduce concurrency. |
{error: 'Maximum limit of ${max_parallel_jobs} jobs per dataset has been exceeded'} | Marketplace Dataset API | You have exceeded the maximum allowed number of parallel jobs for the dataset. | Reduce the number of concurrent jobs, or wait for existing jobs to complete before initiating new ones. |
| This error code implies a rate limit (rare) and auto-throttling by Bright Data (specific to Web Unlocker). | Open a ticket or email support@brightdata.com for assistance. |
500 internal server error
Cause: An unexpected error occurred on the Bright Data API server. These are server-side issues that are typically outside of your direct control.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
Internal server error | Many Scrapers Library endpoints, GET /datasets/v3/snapshots, Marketplace Dataset API | A general, unhandled server-side error occurred. | This is typically a temporary issue. Retry your request after a short delay. If the problem persists, contact Bright Data support with the request details and any error messages. |
Internal error. | Marketplace Dataset API | An unexpected error occurred on the server. | This is a server-side issue. Retry the request. If the problem persists, contact Bright Data support. |
502 bad gateway
Cause: The Bright Data API server received an invalid response from an upstream server.
| Message | Associated Endpoint(s) | Cause | Suggested Action |
|---|---|---|---|
Unexpected error. The server encountered an unexpected error while processing the request. | Marketplace Dataset API | The server encountered an unexpected error while processing the request. | This is typically a temporary server-side issue. Retry the request. If it persists, contact support. |
503 service unavailable
| Message | Associated Endpoint(s) | Cause | Suggested Action |
| Service Unavailable| Specific to Web Unlocker| Browser check failed or browser check wasn’t completed. | This indicates a temporary service unavailability or a browser rendering issue. Retry the request. If it persists, contact support. |
Proxy errors
This section details errors specifically related to Bright Data’s proxy networks.
For proxy-related errors, you can use curl with the -v or -i flags to view all response headers, including custom Bright Data error header fields (x-brd-err-code, x-brd-error, x-brd-err-msg)
- Verbose Output:
curl -v [your_curl_command_options] - Headers Only:
curl -i [your_curl_command_options]
If the error response lacks Bright Data error header fields, the issue likely originates from the target website rather than Bright Data, and you should refer to the overcoming website blocking documentation.
Proxy request error handling configuration
| Value | Description |
|---|---|
pass_dyn | If a request can’t pass via proxy peer, automatically pass it via the Super Proxy. |
block | If a request can’t pass via proxy peer, block it and don’t send via Super Proxy. |
Proxy HTTP error codes
These are the HTTP status codes returned directly by the proxy network, often accompanied by Bright Data-specific error codes.
| HTTP Status Code | Bright Data Error Code (x-brd-err-code) | Description / Error Message (x-brd-error / x-brd-err-msg) | Suggested Action |
|---|---|---|---|
| 400 | (Not specified) | When using the Data center/ISP or gIPs products with the $-ip-x.x.x.x$ targeting flag, the error code 400 can appear in case the IPs under your zone has been refreshed, removed, or simply changed due to system updates. | Go to your Bright Data Zones page and view the updated list of IPs relevant to this zone. |
| 400 | client_10060 | This error typically arises after your BrightData account has been recently suspended. An automatic suspension occurs if your account balance becomes negative. If the suspension extends beyond 24 hours, the static allocated IPs will be released from your account. Upon reactivation, the reallocated IPs may differ from the original ones, thus if the previously allocated IPs are still being targeted - this error is thrown. | Reactivate your account and update your allocated IPs from the Bright Data Zones page. |
| 401 | client_10050 | Associated with HTTP Error 401. | Check your proxy authentication settings and credentials. |
| 402 | policy_20130 | Associated with HTTP Error 402. | Review your account balance and usage policies. |
| 402 | policy_20140 | Associated with HTTP Error 402. | Review your account balance and usage policies. |
| 403 | client_10070 | HTTP 403 response code means you are forbidden from accessing a valid URL. The server processed the request, but it can’t fulfill the request either due to the way the request was sent by the client or due to Bright Data policy, blocking target access. | Review your request method, headers, and target website’s blocking mechanisms. Consider using the Web Unlocker API. |
| 403 | client_10080 | Associated with HTTP Error 403. | Review your request method, headers, and target website’s blocking mechanisms. |
| 403 | client_10090 | Associated with HTTP Error 403. | Review your request method, headers, and target website’s blocking mechanisms. |
| 403 | client_10130 | Associated with HTTP Error 403. | Review your request method, headers, and target website’s blocking mechanisms. |
| 403 | client_10250 | Associated with HTTP Error 403. | Review your request method, headers, and target website’s blocking mechanisms. |
| 403 | policy_20020 to policy_20240 (multiple codes) | The request is being blocked due to a Bright Data policy. | Review Bright Data’s usage policies. Consider adjusting your request patterns or target. For complex blocking, consider the Web Unlocker API. |
| 407 | client_10001 | Proxy authentication required (example message) | Ensure valid proxy credentials (--proxy-user) are included in your request. |
| 407 | client_10002 | Associated with HTTP Error 407. | Check your proxy authentication setup. |
| 407 | client_10010 | Associated with HTTP Error 407. | Check your proxy authentication setup. |
| 407 | client_10020 | Associated with HTTP Error 407. | Check your proxy authentication setup. |
| 407 | client_10030 | Associated with HTTP Error 407. | Check your proxy authentication setup. |
| 407 | client_10040 | Associated with HTTP Error 407. | Check your proxy authentication setup. |
| 407 | policy_20120 | Associated with HTTP Error 407. | Review your proxy policies. |
| 429 | client_10110 | Associated with HTTP Error 429. | Implement a retry mechanism with exponential backoff. Reduce the frequency of your requests. |
| 429 | policy_20220 | Associated with HTTP Error 429. | Review your usage patterns and Bright Data policies. Reduce the frequency of your requests or adjust your usage. |
| 429 | policy_20221 | Associated with HTTP Error 429. | Review your usage patterns and Bright Data policies. Reduce the frequency of your requests or adjust your usage. |
| 401, 411, 444 | (Not specified) | Associated with HTTP Error 401, 411 & 444. | Bad request, usually happens in API requests when headers or cookies missing. |
| 502 | client_10120 | Associated with HTTP Error 502. | This is a server-side issue. Retry the request. If the problem persists, contact Bright Data support. |
| 502 | peer_30030 | Associated with HTTP Error 502, indicating an issue with the proxy peer. | This indicates an issue with the proxy peer. Retry the request. If the problem persists, contact Bright Data support. |
Other specific proxy error messages
These are messages that indicate a specific issue related to your Bright Data proxy zone.
Error Message (x-brd-error / x-brd-err-msg) | Associated Error Code (x-brd-err-code) | Cause | Suggested Action |
|---|---|---|---|
Zone has reached usage limit | target_40001, target_40011 | Your Bright Data zone has reached its predefined usage limit. | Go to your Bright Data control panel at https://brightdata.com/cp/zones to review and modify your zone’s usage limitations. |