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 秒加随机抖动退避。参见临时 IP 封禁规则
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 次及以上 HTTP 429 响应，就会被 Bright Data 临时封禁。该阈值统计的是 429 响应数，而不是请求总数。被封禁的 IP 的所有 API 请求都会被拒绝，临时 IP 封禁会在一小时后自动解除，无需联系 Bright Data 支持团队。

被封禁前如何处理 429 响应？

429 是要求放慢速度的信号，而不是立即重试的信号：

收到 429 后立即停止发送新请求。
如果响应包含 Retry-After 标头，等待其指定的秒数。否则按 2、4、8、16、32 秒退避，并在每次等待中加入随机抖动。
设定固定的重试次数上限。如果 429 响应持续出现，请暂停并降低并发。

仅靠退避不会释放任务容量。429 消息 You have too many running jobs for this dataset 表示您已有 5,000 个活动任务或快照在运行，因此在运行中的任务完成前，请提交更少、更大的任务。

5 分钟内出现 10 次及以上 429 响应，意味着已接近“5 分钟 25 次”的封禁阈值。请立即降低请求速率。共用同一出口 IP 的多个 worker 会累计到同一阈值，因此请在它们之间协调限流：各自独立的重试循环加起来也可能达到 25 次。

我的 IP 已被封禁怎么办？

临时 IP 封禁会在一小时后自动解除，恢复访问无需依赖 Bright Data 支持团队：

停止从被封禁 IP 发出的所有 API 请求，包括重试。
解决导致 429 响应的原因，例如降低并发，或将多个输入合并为更少的任务。
一小时后，以更低的请求速率或并发逐步恢复，避免再次被封禁。

如果影响严重或时间紧迫，或者一小时后 IP 仍被封禁，请联系 Bright Data 支持团队，并提供您的出口公网 IP 地址、受影响的 API 端点、带时区的时间戳以及观察到的错误详情。Bright Data 无法保证立即解除封禁。重试代码见异步指南中的收到 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 错误会怎样？

被封禁前如何处理 429 响应？

我的 IP 已被封禁怎么办？

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

空结果算错误吗？

相关页面