> ## Documentation Index > Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Troubleshoot 4xx and 5xx errors from the Bright Data 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](https://docs.brightdata.com/proxy-networks/errorCatalog) ## 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 \{init\_types\.compr\_update is no longer supported\. Use '{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 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](mailto: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. |