Troubleshooting

Troubleshoot 4xx and 5xx errors from the Bright Data Web Unlocker API, SERP API, Web Scraper API, Marketplace Dataset API and Web Scraper IDE with fixes.

Proxy networks troubleshooting

Error codes and description for proxy networks can be found here

Datasets 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. Bright Data 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	Scraper Studio API, Marketplace Dataset API	The specified request ID or other request details were not found in the Bright Data Marketplace Dataset API.	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 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 Web Unlocker API).	Open a ticket or email [e-mail] 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 Web 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.