Proxy networks troubleshooting
Error codes and description for proxy networks can be found hereDatasets 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 Unlocker API). | 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 Unlocker API). | Open a ticket or email support@brightdata.com for assistance. | Confirm the delivery_id is correct. |
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 Unlocker API | 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. |
Dataset API errors
400 - Bad Request
Indicates that the request was invalid or cannot be processed.| Error Message | Cause |
|---|---|
{validation_errors: ["filter.name is required"]} | The request is missing a required filter parameter (e.g., filter.name). |
{validation_errors: ["Invalid input provided"]} | The input provided in the request is not valid. |
Type ${init_types.compr_update} is no longer supported. Use '${init_types.discover_all}' instead. | The requested operation type is deprecated. |
Type ${init_types.update_existing} is no longer supported. | The requested operation type is no longer supported. |
Type ${init_types.discover_new} is no longer supported. | The requested operation type is no longer supported. |
Initiation reason is required. | The request is missing the required initiation reason. |
This feature is not available. | The requested feature is not supported for the dataset. |
This dataset was rejected. | The dataset was rejected and cannot be processed. |
This dataset is not ready. | The dataset is not in a state where it can be processed. |
This dataset does not support discovery. Supported types: ['${init_types.url_collection}'] | The dataset does not support the requested discovery type. |
Incorrect discovery collector id. | The discovery collector ID provided in the request is invalid. |
View not found. | The requested view is not available. |
This dataset does not support collection. | The dataset does not support the requested collection operation. |
Batch size must be at least 1000. | The batch size specified in the request is below the minimum allowed value. |
{error: 'Snapshot failed'} | The snapshot operation failed. |
{error: 'Snapshot not ready'} | The snapshot is not ready for processing. |
{error: 'Invalid snapshot type'} | The snapshot type provided in the request is invalid. |
{validation_errors: [e.message]} | A validation error occurred, and the specific message is included in the response. |
401 - Unauthorized
Indicates that the user is not authorized to access the requested resource.| Error Message | Cause |
|---|---|
Unauthorized | The API key or authentication credentials provided are invalid or missing. |
402 - Payment Required
Indicates that the user does not have sufficient funds to process the request.| Error Message | Cause |
|---|---|
{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)'} | The user’s account balance is insufficient to process the request. |
403 - Forbidden
Indicates that the user does not have permission to access the requested resource.| Error Message | Cause |
|---|---|
Access denied. | The user does not have the necessary permissions to access the resource. |
Cannot skip billing. | The user attempted to skip billing, which is not allowed. |
404 - Not Found
Indicates that the requested resource could not be found.| Error Message | Cause |
|---|---|
{error: 'Dataset not found'} | The specified dataset ID does not exist. |
{error: 'Snapshot not found'} | The specified snapshot ID does not exist. |
Dataset does not exist. | The dataset referenced in the request does not exist. |
Request not found. | The specified request ID does not exist. |
422 - Unprocessable Entity
Indicates that the request was well-formed but could not be processed due to semantic errors.| Error Message | Cause |
|---|---|
{error: 'Provided filter did not match any records'} | The filter provided in the request did not match any records in the dataset. |
429 - Too Many Requests
Indicates that the user has exceeded the rate limit or the maximum number of parallel jobs.| Error Message | Cause |
|---|---|
{error: 'Maximum limit of ${max_parallel_jobs} jobs per dataset has been exceeded'} | The user has exceeded the maximum allowed number of parallel jobs for the dataset. |
500 - Internal Server Error
Indicates that an unexpected error occurred on the server.| Error Message | Cause |
|---|---|
Internal error. | An unexpected error occurred on the server. |
502 - Bad Gateway
Indicates that the server received an invalid response from an upstream server.| Error Message | Cause |
|---|---|
| Unexpected error. | The server encountered an unexpected error while processing the request. |