> ## 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.

# Scraper Studio 错误代码

> 查询 Bright Data Scraper Studio 的错误代码、状态码和警告，了解每种采集失败的含义以及建议的处理方式。

本参考文档列出 Bright Data Scraper Studio 在采集运行过程中，爬取、解析器、请求、校验或投递环节失败时返回的错误代码，以及每个代码对应的建议操作。

请结合 `error_code`、`status_code` 和原始 `error` 消息一起判断失败原因和后续处理方式。

<Note>
  这些是 Scraper Studio 的采集错误，不是 API 认证错误或 API 请求错误。关于 Scraper Studio 之外返回的代理层 HTTP 错误，请参见[错误目录](/cn/proxy-networks/errorCatalog)。
</Note>

## 如何解读 Scraper Studio 错误？

Scraper Studio 使用五个系统字段描述每条记录的状态。

| 字段             | 类型        | 含义                                                                                                       |
| -------------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `error_code`   | 机器可读标识符   | 爬取失败的原因，例如 `dead_page`、`bad_input`、`blocked`、`crawl_error`、`parse_error` 或 `load_sitemap`。可用于筛选、自动化或重试逻辑 |
| `error`        | 人类可读消息    | 详细的失败原因，例如 `Crawler error: Cannot find product title`                                                    |
| `status_code`  | 类 HTTP 数值 | 爬取结果的概要。该字段为可选，详见下方状态码表                                                                                  |
| `warning`      | 人类可读消息    | 记录已投递，但存在需要复查的非致命问题                                                                                      |
| `warning_code` | 机器可读标识符   | `warning` 的机器可读版本，例如 `dead_page` 或 `validation`                                                          |

请基于 `error_code` 而非原始 `error` 字符串编写判断逻辑，因为错误消息文本会随爬虫更新而变化：

```js theme={null}
if (line.error_code === 'dead_page') {
  // 处理已失效或已删除的 URL
}
```

### Scraper Studio 状态码分别代表什么？

`status_code` 以类 HTTP 数值的形式概括爬取结果。

| 状态码 | 含义                                      |
| --- | --------------------------------------- |
| 400 | 请求错误或页面响应无效                             |
| 403 | 目标网站拒绝或阻止访问                             |
| 404 | 页面不存在、已被删除或 URL 无效                      |
| 407 | 账户被暂停或访问受限                              |
| 408 | 请求超时，目标网站未在规定时间内响应                      |
| 421 | 请求被路由到了错误的服务器                           |
| 429 | 请求过多，已触发速率限制                            |
| 500 | 在 Scraper Studio 收到有效页面响应之前，爬取、代理或导航已失败 |
| 503 | 目标网站或服务暂时不可用、过载或超时                      |

<Warning>
  `status_code` 有时会缺失或为 `undefined`，因为部分错误路径不会分配数字状态码。请将 `status_code` 视为可选字段，不要假定它始终存在。
</Warning>

## 错误与警告有什么区别？

错误表示该记录采集失败；警告表示该记录已投递，但存在需要复查的问题。

* **错误（Error）：** 记录失败，应视为未成功。失败记录通常包含 `error`、`error_code` 和 `status_code`
* **警告（Warning）：** 记录已投递，但存在需要复查的问题。带非致命问题的已投递记录通常包含 `warning`、`warning_code` 和 `status_code`
* **成功记录：** `error`、`error_code`、`warning` 和 `warning_code` 均未填充

出现警告的情况包括：部分爬取返回了数据但同时存在问题、某个通常判定为失败的条件被配置为非错误，或输出校验发现问题但仍保留了该记录。

当 `dead_page` 错误被降级为警告时，输出中会包含：

```text theme={null}
warning_code = dead_page
warning = Dead page detected
```

Schema 校验警告通常使用：

```text theme={null}
warning_code = validation
```

同一个底层问题既可能表现为错误，也可能表现为警告，具体取决于爬虫逻辑、校验规则和输出 schema 设置。

## Scraper Studio 错误来自哪里？

Scraper Studio 的错误来自以下三个层级之一。

### 哪些原因会导致爬虫错误？

爬虫错误来自爬虫的交互代码、解析器代码或输入处理，例如无效输入、`wait_element_timeout`、`parse_error`、`click_timeout`、`dead_page`、`bad_input` 和 `blocked` 等。

通常通过更新爬虫逻辑、解析器选择器、校验规则或输入数据来解决。

### 哪些原因会导致代理和解锁器错误？

代理和解锁器错误来自 Bright Data 的代理、路由或解锁层，例如代理连接问题、目标网站封锁、地理位置或 zone 配置问题、无可用节点以及速率限制等。

通常需要重试、降低请求速率、更改国家或地理位置设置；若问题持续存在，请联系 Bright Data 支持团队。

### 哪些原因会导致平台和基础设施错误？

平台和基础设施错误来自 Scraper Studio 平台、浏览器 worker、解析器沙箱、存储层或内部基础设施，例如 worker 超时、浏览器断开连接、解析器超出内存限制、上传失败以及 WebSocket 连接问题等。

这类错误通常是临时性的，重试即可解决。若问题持续存在，请提交支持工单，并附上爬虫 ID、作业 ID、失败的输入以及原始错误消息。

## 常见爬虫错误代码

这类错误代码表示爬虫执行阶段的问题。请求失败的原因可能是输入无效、页面元素缺失或发生变化、目标网站封锁、解析问题、速率限制、CAPTCHA 处理，或爬虫逻辑需要更新。

| 错误代码                           | 含义                                                          | 建议操作                                                                                                                              |
| ------------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `dead_page`                    | 爬虫检测到该页面不存在或已不再相关。                                          | 手动确认该页面是否仍可打开。移除已失效的 URL，或修复会产生过期链接的发现逻辑。                                                                                         |
| `bad_input`                    | 爬虫将该输入标记为无效并跳过重试。常见于必填输入字段缺失、URL 无效或页面类型不符合预期。              | 在触发爬虫前校验输入。移除无效 URL，或更新发现逻辑以避免不支持的页面类型。                                                                                           |
| `blocked`                      | 爬虫代码中调用了 `blocked()` 函数，或目标网站拒绝访问该页面。                       | 稍后重试、降低请求速率，或检查国家、会话、CAPTCHA 和封锁处理逻辑。                                                                                             |
| `crawl_error`                  | 发生了一般性的爬取执行错误。常见于页面未正确加载、所需页面数据缺失、浏览器会话关闭，或爬虫代码尝试读取不存在的数据。  | 针对失败的输入打开 Debug crawl 或 Crawl inspector。检查页面加载情况、添加空值校验，并重新运行失败的页面。                                                               |
| `wait_element_timeout`         | 爬虫等待的元素未在规定时间内出现。                                           | 确认选择器仍然存在且稳定。若页面加载较慢，可增加超时时间或处理其他页面布局。                                                                                            |
| `ajax_request_error`           | 页面执行期间某个后台请求失败或超时。                                          | 在预览或调试模式下检查网络请求。若该请求是可选的，可放宽校验或添加兜底逻辑。                                                                                            |
| `collector_request_validation` | 自定义请求校验规则拒绝了某个 AJAX 或网络响应，通常来自 `verify_requests()` 逻辑。      | 检查校验回调，确认被拒绝的响应是否必需。若该请求是可选的，可放宽规则。                                                                                               |
| `captcha_timeout`              | CAPTCHA 未在预期时间内完成求解。                                        | 重试爬取，并检查目标网站是否反复弹出 CAPTCHA。检查 CAPTCHA 处理逻辑和作业截止时间设置。                                                                              |
| `close_popup_fail`             | Scraper Studio 未能关闭弹窗，例如同意管理弹窗或模态框。                         | 检查弹窗选择器是否变化或仅在特定条件下出现。更新弹窗处理逻辑；若弹窗不影响数据提取，可让爬虫忽略它。                                                                                |
| `click_timeout`                | 点击操作未在超时时间内完成。元素可能缺失、隐藏、禁用或不可点击。                            | 确认选择器匹配的是可见且可点击的元素。在点击前添加 `wait(selector)`，或更新点击逻辑。                                                                               |
| `tag_response`                 | 标记响应（tagged response）回调失败，或标记响应返回了非预期的状态或格式。                | 检查标记响应回调，确认预期的响应存在。在 IDE 的浏览器网络面板中确认该响应正常加载，并在读取字段前添加检查。                                                                          |
| `load_sitemap`                 | Scraper Studio 未能加载或解析 sitemap。原因包括抓取失败、请求超时或 sitemap 格式无效。 | 手动打开 sitemap URL，确认其可访问且格式有效。                                                                                                     |
| `load_more_timeout`            | 爬虫等待加载更多条目，但超时前没有新条目出现。                                     | 确认"加载更多"选择器和列表容器仍然存在。在没有更多结果时添加停止条件。                                                                                              |
| `child_input_size_validation`  | 由 `next_stage()` 创建的子输入超出了允许的输入大小。                          | 减少传递给 `next_stage()` 的数据，仅传递下一阶段所需的字段，例如 URL、ID 或少量元数据。                                                                           |
| `detect_block`                 | Scraper Studio 检测到封锁页面内容，例如"Access Denied"、登录墙或其他已知封锁模式。    | 手动打开失败的页面，确认是否显示封锁页面。若大量输入失败，请降低请求速率或检查位置和会话行为。                                                                                   |
| `ERR_INVALID_URL`              | URL 值无效或格式不受支持。                                             | 在触发爬虫前校验输入 URL。确保 URL 包含 `http://` 或 `https://`，且不含非法字符。                                                                          |
| `not_supported_cmd`            | 爬虫使用了当前 worker 类型不支持的函数。                                    | 更换 worker 类型或替换该函数。click、scroll、type 和 wait 等仅限浏览器的操作需使用 Browser worker。参见 [Worker 类型](/cn/datasets/scraper-studio/worker-types)。 |
| `detached_element`             | 爬虫引用的元素在操作完成前已被移除或重新渲染。                                     | 在交互前重新选取元素。在页面更新后添加等待，并避免跨 DOM 变更保存元素句柄。                                                                                          |
| `timeout`                      | 爬虫在等待元素、请求、响应或页面操作完成时超时。                                    | 确认预期的元素或响应确实存在。仅在必要时增加超时时间，并为可选或加载较慢的内容添加兜底逻辑。                                                                                    |

### `block` 与 `blocked` 有什么区别？

`block` 和 `blocked` 是两个不同的错误代码。`blocked` 由爬虫逻辑触发，`block` 由抓取页面的下层触发。

`blocked` 通常由爬虫逻辑触发。当爬虫检测到封锁页面、登录墙、CAPTCHA 页面或其他应标记为封锁的情况时，会调用 `blocked()`：

```js theme={null}
blocked('Login page was shown');
```

`block` 通常来自导航、请求拒绝、目标网站封锁或代理层响应处理，可能携带目标网站或上游层返回的真实 HTTP 状态码。`block` 已观察到的状态码包括：

```text theme={null}
400, 401, 403, 404, 405, 409, 410, 418, 429, 500, 503
```

简而言之：

* `blocked` 是采集器层面的封锁检测，通常由爬虫逻辑触发
* `block` 是目标网站、代理或导航层面的拒绝，通常带有 HTTP 状态码

## 导航和浏览器错误代码

这类错误代码表示导航或浏览器加载问题。失败原因可能是页面未在规定时间内加载、浏览器无法访问该 URL、目标网站持续保持网络请求打开，或连接在完成前超时或关闭。

| 错误代码                             | 含义                                                                | 建议操作                                                                                      |
| -------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `bad_navigate`                   | 浏览器无法导航到请求的 URL。                                                  | 手动打开该 URL，检查是否发生重定向或访问被拒。若为临时故障，可重试爬取。                                                    |
| `navigation_timeout`             | 页面未在允许时间内完成导航。                                                    | 仅在必要时增加导航超时时间。建议使用 `wait(selector)` 或其他 `wait_until` 策略，而非等待整页加载完成。                       |
| `domcontentloaded_event_timeout` | 浏览器等待 `DOMContentLoaded` 事件超时，页面未在规定时间内达到预期加载状态。                  | 若无需整页加载，可使用 `navigate(input.url, { wait_until: 'navigate' })`，随后对所需元素使用 `wait(selector)`。 |
| `networkidle_event_timeout`      | 浏览器等待网络活动进入空闲状态时超时。某些页面因持续保持后台请求而永远无法达到网络空闲。                      | 对于存在持续后台流量的页面，不要依赖完全网络空闲。请使用 `wait_until: 'navigate'` 并等待特定选择器。                           |
| `load_event_timeout`             | 页面未在规定时间内触发完整的 `load` 事件。                                         | 若非必需，请勿等待整页加载。对解析器所需的内容使用基于选择器的等待。                                                        |
| `document_load_failed`           | 浏览器已开始导航，但主文档加载失败。原因包括 HTTP 失败、SSL/TLS 问题、空响应、凭据缺失、重定向问题或代理与节点问题。 | 重试并确认目标 URL 可在浏览器中打开。若持续失败，可尝试更换地理位置，或提交支持工单并附上作业 ID 和完整错误信息。                             |
| `net_err_timed_out`              | 网络请求超时。                                                           | 重试并检查目标网站的稳定性。若大量输入受影响，请降低并发数。                                                            |
| `net_err_closed`                 | 目标网站意外关闭了连接。                                                      | 检查网站是否可用并重试。若频繁出现，请检查封锁或速率行为。                                                             |
| `net_err_cert_date_invalid`      | 服务器提供的 SSL/TLS 证书在当前日期无效。                                         | 确认目标 URL 可在浏览器中正常打开，且网站证书有效。                                                              |
| `net_err_http2_protocol_error`   | 浏览器在加载目标页面或资源时遇到 HTTP/2 协议错误。                                     | 重试请求。若持续出现，请确认目标网站在浏览器中能否正常加载。                                                            |
| `net_err_cert_authority_invalid` | 目标网站的 SSL/TLS 证书由不受信任或未知的证书颁发机构签发。                                | 确认目标 URL 可在浏览器中正常打开，且证书受信任。                                                               |

### 浏览器和基础设施生命周期错误

这类错误代码表示浏览器会话、runner 或浏览器控制连接在爬取过程中被中断，通常是临时性的平台或浏览器生命周期错误。

常见的生命周期错误代码包括 `runner_disconnected`、`network_error`、`cdp_conn_err`、`cdp_cmd_timeout`、`cdp_disconnect`、`bad_browser`、`browser_disconnected` 和 `ipc_timeout`。

**建议操作：** 重试该作业。若错误持续存在，请提交支持工单，并附上作业 ID、响应 ID、失败的输入以及原始错误消息。

### 速率限制类错误

`global_rate_limit` 和 `bucket_rate_limit` 表示对目标域名的请求受到了速率限制。通常出现在目标网站对高请求量敏感，或并发请求过多的情况下。

**建议操作：** 短暂延迟后重试。若问题反复出现，请降低并发数并将作业排队，而不是并行运行大量作业。

## 作业生命周期错误代码

这类错误代码表示采集因运行时长、截止时间、取消操作或页面数量限制而未能完成。

| 错误代码               | 含义                                           | 建议操作                                                       |
| ------------------ | -------------------------------------------- | ---------------------------------------------------------- |
| `job_run_timeout`  | 采集或爬取超出了允许的运行时长。常见于长时间等待、页面操作缓慢或 CAPTCHA 求解。 | 优化爬虫逻辑，检查是否存在循环、长时间等待或反复求解 CAPTCHA。减少每次请求的工作量，或在可行时延长截止时间。 |
| `crawl_timeout`    | 爬虫未在内部超时时间内返回结果。                             | 重试爬取。若反复出现，请简化爬取逻辑或降低页面复杂度。                                |
| `deadline_timeout` | 作业达到了配置的截止时间。                                | 延长截止时间或减少每次请求的工作量。对于大型工作负载，请将作业拆分为多次较小的运行。                 |
| `too_many_pages`   | 作业创建了过多子页面。                                  | 减少每个输入生成的子页面数量。对于高扇出作业，请使用批量采集。                            |
| `uncrawled_page`   | 在页面完成爬取前就请求了页面结果，通常是因为达到了作业截止时间。             | 延长截止时间，或减少爬虫创建的页面数量。                                       |
| `aborted_page`     | 作业被取消，因此爬取被中止。                               | 若作业为主动取消，则无需处理。否则请重新运行受影响的输入。                              |

## 基础设施和存储错误代码

这类错误代码表示平台、worker、存储或投递方面的问题。采集失败的原因可能是内部服务不可用、worker 过载、结果过大，或投递到外部目标失败。

| 错误代码                   | 含义                                     | 建议操作                                           |
| ---------------------- | -------------------------------------- | ---------------------------------------------- |
| `infra_error`          | 发生内部基础设施错误。                            | 重试请求。若问题持续存在，请联系支持团队并提供作业 ID 或响应 ID。           |
| `page_too_big`         | 加载的页面超出了 Scraper Studio 16 MB 的页面大小限制。 | 减少每页采集的数据量。避免存储大段 HTML 或不必要的字段。                |
| `crawl_request_failed` | 爬取 runner 在多次重试后仍无法连接到爬虫 worker。       | 重试该作业。若问题持续存在，请上报支持团队。                         |
| `worker_too_busy`      | 爬虫 worker 过载。                          | 稍后重试并降低并发数。                                    |
| `external_upload_fail` | 将结果或媒体文件上传到外部目标失败。                     | 检查投递目标的配置、凭据、权限和路径设置。                          |
| `failed_media_upload`  | Scraper Studio 未能保存媒体文件。               | 重试失败的页面，并确认媒体 URL 可访问。若持续失败，请检查投递和存储设置或联系支持团队。 |

## 代理和解锁器错误代码

这类错误代码表示 Scraper Studio 与底层代理网络之间存在路由或连接问题，通常出现在代理网络无法与目标网站建立或维持稳定连接时。

| 错误代码             | 含义                                                       | 建议操作                                             |
| ---------------- | -------------------------------------------------------- | ------------------------------------------------ |
| `proxy`          | 导航或请求期间发生代理层故障。可能原因包括无可用节点、DNS 解析失败、SSL 问题、目标拒绝、超时或防护页面。 | 重试，必要时更换国家，并确认目标可访问。若持续失败，请联系支持团队并提供作业 ID 和原始错误。 |
| `proxy_error`    | 代理层无法连接到目标网站，或收到了非预期的上游响应。                               | 重试并确认目标 URL。若问题反复出现，可尝试其他国家，或提供作业 ID 和错误详情上报。    |
| `net_err_tunnel` | 浏览器无法通过代理建立隧道连接。                                         | 检查网站是否可用并重试。若大量输入持续出现该问题，请上报。                    |
| `no_peers`       | Scraper Studio 未能与节点建立连接。                                | 稍后重试，或移除国家、位置、会话等限制性节点设置。                        |

## 解析器和负载错误代码

这类错误代码表示解析器执行或负载大小问题。失败原因可能是解析器代码遇到无效或缺失的数据、发送给解析器的负载过大，或解析器执行超出内存或 CPU 限制。

| 错误代码                          | 含义                                                                           | 建议操作                                    |
| ----------------------------- | ---------------------------------------------------------------------------- | --------------------------------------- |
| `parse_error`                 | 解析器代码在提取或处理数据时失败。常见原因包括语法错误、内容被封锁或无效、字段缺失、URL 无效，或从 `null`、`undefined` 读取属性。 | 使用失败的输入运行预览并检查解析器代码。添加防御性检查并校验选择器。      |
| `parse_request_payload_large` | 发送给解析器的负载超出了大小限制。                                                            | 减少发送给解析器的数据量，仅提取所需的 HTML 片段或响应字段。       |
| `parse_mem_limit_exceeded`    | 解析器执行超出内存限制，通常由超大 HTML、JSON、数组或内嵌数据导致。                                       | 减小解析器负载，避免在内存中存储大对象，仅提取所需字段。            |
| `parse_cpu_limit_exceeded`    | 解析器执行超出 CPU 限制，通常由大量循环、正则或数据转换导致。                                            | 简化解析器逻辑，减少对大数据集的循环，并将非必要处理移出解析器。        |
| `parse_req_error`             | 解析器请求负载超出了允许的字段大小。                                                           | 减小请求或解析负载的体积。避免将超大字段、文件或 HTML 块传入解析器处理。 |

## 访问和权限错误代码

这类错误代码表示访问或合规方面的问题。请求被终止的原因是目标受 Bright Data 合规保护机制限制，或账户权限需要复核。

| 错误代码   | 含义                    | 建议操作                                                |
| ------ | --------------------- | --------------------------------------------------- |
| `brul` | 目标受 Bright Data 合规限制。 | 如需访问，请联系 `compliance@brightdata.com` 并申请该受限资源的访问权限。 |

## 采集失败时的排查流程

当采集运行返回错误时，请按以下顺序排查。

1. 查看 `error_code`。
2. 查看 `status_code`（若存在）。
3. 阅读原始 `error` 消息。
4. 手动打开失败的 URL，确认页面是否存在且可访问。
5. 使用 Debug crawl 或 Crawl inspector 检查失败的输入、爬取阶段、子页面、文件、警告和输出记录。
6. 若错误与解析器相关，请运行预览并检查 HTML、Output 和 Last errors。
7. 若大量输入出现相同错误，请检查请求速率、并发数、封锁情况、worker 类型以及目标网站近期的变更。
8. 若问题持续存在，请提交支持工单，并附上爬虫 ID、作业或响应 ID、失败的输入以及原始错误消息。

## 常见问题

### 为什么失败记录中没有 `status_code`？

部分 Scraper Studio 错误路径不会分配数字状态码，因此 `status_code` 有时会缺失或为 `undefined`。请将该字段视为可选，并改用 `error_code` 编写判断逻辑。

### 出现警告是否意味着记录丢失？

不是。警告表示记录已投递，但存在需要复查的问题，例如部分爬取、被配置为非错误的条件，或输出校验问题。只有包含 `error` 和 `error_code` 的记录才算失败。

### 哪些错误适合自动重试？

适合自动重试的是临时性的平台、浏览器生命周期、代理和速率限制错误，例如 `infra_error`、`runner_disconnected`、`browser_disconnected`、`worker_too_busy`、`proxy_error`、`global_rate_limit` 和 `bucket_rate_limit`。`bad_input`、`ERR_INVALID_URL` 和 `dead_page` 不应重试，这些需要修复输入或发现逻辑。