Overview
Troubleshooting
This section covers errors encountered when interacting directly with Bright Data’s Unlocker API, 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 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. |
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. |
Appendix
Sources:- http://cvs.brightdata.com/cvs/zon/pkg/www/dca/pub/util.js?rev=1.197
- pkg/www/dca/dataset_ext_api.js
Some error codes (e.g., 400, 404) may have multiple causes, as outlined above.
Error messages are designed to provide clear feedback to users about the issue and how to resolve it.
For errors with dynamic content (e.g., balance or job limits), placeholders like${max_parallel_jobs}or${init_types}are replaced with actual values at runtime.