Scraper API 错误代码

本参考文档列出 Bright Data Scraper API 返回的错误、每种错误的含义以及处理方式。 Scraper API 错误分为两层：

HTTP 错误：请求本身失败。API 返回 4xx 状态码，不会运行任何任务
记录错误：请求成功，但某个输入无法抓取。失败的记录会在结果中带有 error_code 字段

Scraper API 的 HTTP 错误是什么意思？

Scraper API 的 POST /datasets/v3/trigger 和 POST /datasets/v3/scrape 会返回以下 HTTP 错误。

状态码	消息	含义	是否重试	处理方式
400	`{"error": "Invalid input provided", "code": "validation_error", "errors": [[FIELD, REASON]]}`	某个输入字段未通过校验。`errors` 会指出字段和原因，例如 `["url", "This field must be a valid url"]`	否	修正 `errors` 中指出的输入值后重新发送
400	`{"error": "Parser cannot parse input: ...", "code": "parse_error"}`	请求体不是有效的 JSON	否	修正 JSON 后重新发送
400	`No data to trigger`	请求中没有任何输入	否	至少发送一个输入
400	`Should be at least LIMIT inputs`	请求中的输入数量少于该爬虫的要求。由 `/trigger` 返回	否	至少发送消息中指出的输入数量
401	`Credentials are missing`	未发送 `Authorization` 标头	否	发送 `Authorization: Bearer YOUR_API_KEY`
401	`Auth method is not supported`	`Authorization` 标头格式不受支持	否	发送 `Authorization: Bearer YOUR_API_KEY`
401	`Invalid credentials`	API 密钥错误	否	检查 API 密钥后重新发送
404	`Collector not found`	请求中缺少 `dataset_id` 查询参数	否	添加 `dataset_id` 查询参数
404	`dataset does not exist`	没有与该 `dataset_id` 匹配的爬虫	否	检查 `dataset_id` 的值
429	`You have too many running jobs for this dataset. Please wait until some of them finish or consider combining multiple inputs into a single request. Running jobs: RUNNING_JOBS>=JOBS_LIMIT`	超过了并发任务上限（5,000 个活动任务或快照）	是，等待后重试	等待 `Retry-After` 标头指定的秒数，否则按 2、4、8、16、32 秒退避。参见 429 封禁规则
202	`Your request is still in progress and cannot be retrieved in this call.`	不是错误。`/scrape` 请求运行超过 1 分钟，任务转为异步继续运行。响应体中带有 `snapshot_id`	否	使用 `snapshot_id` 轮询监控进度，然后下载快照

除非某行注明了具体端点，/trigger 和 /scrape 返回的消息相同。validation_error 和 parse_error 为 JSON 响应体，其他消息均为纯文本。

频繁收到 429 错误会怎样？

任何 IP 在 5 分钟内收到 25 次及以上 429 响应，就会被 Bright Data 封禁。被封禁的 IP 的所有 API 请求都会被拦截，直到 Bright Data 支持团队解除。 429 是要求放慢速度的信号，而不是立即重试的信号：

收到 429 后立即停止发送新请求。
等待 Retry-After 标头指定的秒数。如果没有该标头，按 2、4、8、16、32 秒退避。
如果 429 响应持续出现，请降低并发。

5 分钟内出现 10 次及以上 429 响应，意味着已接近“5 分钟 25 次”的封禁阈值。请立即降低请求速率。

重试代码见异步指南中的收到 429 Too Many Requests 错误？。

Scraper API 的记录错误是什么意思？

记录错误表示 Scraper API 任务已运行，但某个输入没有返回数据。只有在请求中设置 include_errors=true 时，失败的记录才会出现在结果中。请根据 error_code 字段进行分支处理，而不是依赖自由文本的 error 消息，因为消息文本会随爬虫更新而变化。 Bright Data 不对失败的记录收费。

`error_code`	含义
`dead_page`	页面不存在或已不可用，例如 404 或商品已下架
`bucket_rate_limit`	对目标域名的请求正在被限速
`global_rate_limit`	对目标域名的请求正在被限速

以下是在 POST /datasets/v3/scrape 中设置 include_errors=true 时返回的 dead_page 记录。请求本身返回 HTTP 200：

[
  {
    "timestamp": "2026-09-30T08:37:27.027Z",
    "input": {
      "url": "https://www.amazon.com/dp/B09XXEFFA4",
      "asin": "",
      "zipcode": "",
      "language": ""
    },
    "error": "The navigation resulted in a dead page (404 status code)",
    "error_code": "dead_page"
  }
]

记录中保留了原始 input，便于将错误与您发送的 URL 对应起来。完整的记录错误代码列表请参见 Scraper Studio 错误代码。

空结果算错误吗？

不算。空结果（[]）表示任务没有返回数据，不是 HTTP 错误。要查看某个输入为何没有返回数据，请带上 include_errors=true 重新发送请求，并查看每条记录的 error_code。

开始使用

数据提取

网页搜索

AI 训练数据

代理网络

Scraper API 的 HTTP 错误是什么意思？

频繁收到 429 错误会怎样？

Scraper API 的记录错误是什么意思？

空结果算错误吗？

相关页面

​Scraper API 的 HTTP 错误是什么意思？

​频繁收到 429 错误会怎样？

​Scraper API 的记录错误是什么意思？

​空结果算错误吗？

​相关页面

Scraper API 的 HTTP 错误是什么意思？

频繁收到 429 错误会怎样？

Scraper API 的记录错误是什么意思？

空结果算错误吗？

相关页面