Skip to main content
This reference lists the errors the Bright Data Scraper API returns, what each one means and what to do about it. Scraper API errors come in two layers:
  • HTTP errors: the request itself failed. The API answers with a 4xx status and no job runs
  • Record errors: the request succeeded, but one input could not be scraped. The failed record carries an error_code field inside the results

What do the Scraper API HTTP errors mean?

The Scraper API returns these HTTP errors from POST /datasets/v3/trigger and POST /datasets/v3/scrape. Unless a row names one endpoint, /trigger and /scrape return the same message. The validation_error and parse_error bodies are JSON. Every other message is plain text.

What happens if I get too many 429 errors?

Bright Data applies a temporary IP block to any IP that receives 25 or more HTTP 429 responses within 5 minutes. The threshold counts 429 responses, not total requests. A blocked IP is refused on every API request, and the temporary IP block expires automatically after one hour. You do not need to contact Bright Data support for block removal.

How do I handle 429 responses before a block?

Treat a 429 as a signal to slow down, not to retry at once:
  1. Stop sending new requests as soon as you receive a 429.
  2. Wait the number of seconds in the Retry-After header when the response includes one. Otherwise back off 2, 4, 8, 16 and 32 seconds, with random jitter added to each wait.
  3. Stop after a fixed number of retries. If 429 responses persist, pause and reduce concurrency.
Backoff alone does not free job capacity. The 429 message You have too many running jobs for this dataset means you already run 5,000 active jobs or snapshots, so submit fewer, larger jobs until running jobs finish.
Ten or more 429 responses within 5 minutes means you are close to the 25-in-5-minutes block threshold. Reduce the request rate right away. Workers that share one outbound IP count toward the same threshold, so coordinate throttling across them: independent retry loops can reach 25 responses together.

What do I do if my IP is already blocked?

The temporary IP block expires automatically after one hour, so recovery does not depend on Bright Data support:
  1. Stop all API requests from the blocked IP, including retries.
  2. Fix the cause of the 429 responses, for example lower concurrency or combine inputs into fewer jobs.
  3. After the hour passes, resume gradually at a lower request rate or concurrency to avoid another block.
If the impact is critical or time-sensitive, or the IP is still blocked after one hour, contact Bright Data support with your outbound public IP address, the affected API endpoint, timestamps with the time zone and the error details you observed. Immediate block removal is not guaranteed. The retry code is in Getting a 429 Too Many Requests error? on the async guide.

What do Scraper API record errors mean?

A record error means the Scraper API job ran, but one input returned no data. The failed record appears in the results only when the request sets include_errors=true. Branch on the error_code field, not on the free-text error message, because the message text changes as scrapers are updated. Bright Data does not charge for failed records. A dead_page record from POST /datasets/v3/scrape with include_errors=true looks like this. The request itself returns HTTP 200:
The record keeps the original input, so you can match the error back to the URL you sent. For the full list of record error codes, see Scraper Studio error codes.

Is an empty result an error?

No. An empty result ([]) means the job returned no data. It is not an HTTP error. To see why an input returned nothing, resend the request with include_errors=true and read the error_code on each record.