跳转到主要内容
本文介绍如何区分代理错误与其他错误，如何分析错误，以及如何排查并解决使用 Bright Data 代理服务时遇到的问题。

​
我如何查看 Bright Data 代理服务的健康状态？

Bright Data 会在此页面发布其产品与服务状态： https://brightdata.com/network-status 。在此页面，你可以查看你所使用的产品或全球可用性是否存在问题或事件。你还可以注册电子邮件提醒，当可用性变化或出现大范围事件时将收到通知。

​
如果我发现正在使用的代理网络存在当前事件，该怎么办？

首先，你需要检查你的业务是否受到影响。两个主要指标是响应时间下降（变慢）或错误率上升。如果出现其中任何一种情况，请降低处理速率，并继续下一步排查问题。

​
如何判断我遇到的错误是否来自 Bright Data 代理？

在使用代理时，你可能会遇到并非由 Bright Data 引起的错误。要识别错误来源，请检查响应头中是否包含 Bright Data 的错误字段，我们在这些字段中按代理层级覆盖了大多数错误。 如果你仍无法访问目标网站，或收到 HTTP 状态 200 但没有预期数据，则很可能已被目标网站屏蔽。在本文： 突破网站封锁 中，我们提供了一些最佳实践。

​
在其他软件中测试 Bright Data 代理时出现 “Proxy Error” 如何解决？

许多软件工具与实用程序使用 Bright Data 代理，并提供 “Test proxy” 功能。当你点击 “Test proxy” 并看到通用的 “Proxy Error” 错误时，该问题可能来自多种原因。

​
常见问题与解决方案

​
Bright Data 代理错误排查

​
Bright Data 的代理错误格式与标准现支持 RFC9209

自 2025 年 10 月起，Bright Data 在响应负载中支持两组用于传递代理错误的头字段：
  1. 私有的 x-brd-* 字段：x-brd-err-code 与 x-brd-err-msg
  2. 标准 RFC9209 的 Proxy-Status 响应头格式。
Proxy-Status 标准字段将在 2026 年逐步替代所有 x-brd-* 字段。

​
什么是 RFC9209？

RFC9209 是关于如何在代理响应头中传递代理错误的标准。Bright Data 正在采用该标准并将其应用于所有错误目录。这将帮助客户代码与使用代理作为基础设施的第三方工具更快识别和解决代理交互问题。 你可以在此处了解更多内容： The Proxy-Status HTTP Response Header

​
如何实现 RFC9209？

​
Proxy-Status HTTP 头示例


Proxy-Status: brd.brighdata.io;
received-status=400;
error=destination_ip_unroutable;
details="client-10060: Requested IP ##.##.##.## is not allocated to this zone. Select an IP that is allocated to this zone or skip the -ip parameter in proxy username."

​
实现说明

  1. 解析响应头：确保你的系统能够解析 HTTP 响应中的 Proxy-Status 头。
  2. 提取相关字段：
    • received-status：提供收到的 HTTP 状态码
    • error：描述遇到的核心错误
    • details：包含具体错误代码及进一步信息
    • 中第一个字段为 Bright Data 错误代码（如 client_10060）并以冒号分隔
    • 你可以直接使用此前缀浏览错误文档，将错误代码中的 _ 替换为 -：
      https://docs.brightdata.com/cn/proxy-networks/errorCatalog#[Bright data error code]
      示例 client_10060：
      https://docs.brightdata.com/cn/proxy-networks/errorCatalog#client-10060
  3. 根据这些结构化代码调整错误处理流程，以改进调试效率并确保代理正常运行。

​
Bright Data HTTP 代理头字段

以下字段在发送 HTTP 或 HTTPS 请求时返回：
FieldDescriptionExamplesREST API Field Name
HTTP Error协议错误码404 或 502status_code
x-brd-err-codeBright Data 模块与错误代码client_10001error_code
x-brd-errorBright Data 主错误信息Authentication failederror
x-brd-err-msgBright Data 详细错误与操作建议Authentication failed. Please check your credentials or review your account status and billing settings.error_message
Proxy-StatusRFC9209 兼容响应头，包括代理服务器、HTTP 状态和指向 Bright Data 错误代码的详情字符串Proxy-Status: brd.superproxy.io; received-status=407; error="http_request_denied"; details="client_10000: Invalid authentication: check credentials and retry. Bright Data credentials include your account ID, zone name and password"Not supported

​
获取 HTTP 头字段

​
从命令行测试

你可以在 shell 终端使用 curl 命令并加上 -v 或 -i 查看设置或复现问题。这些选项会打印所有头字段，包括自定义错误代码与消息。 
curl -v [rest of curl command options]
若想仅查看响应头，可使用： 
curl -i [rest of curl command options]
你也可以使用 nc 命令打印字段： 
echo "[tcp nc inputs]" | nc -C -v brd.superproxy.io 33335
nc 输入中可能包含 “空行”，这些对于正确测试是必需的。

​
curl 命令片段

你所使用 zone 的 Overview 标签中提供包含全部参数的 curl 命令片段。

​
通过编程语言访问

Bright Data HTTP 头字段可如同其他 HTTP 头一样在你的程序中读取。

​
通过 Bright Data 的 Proxy REST API 访问

Bright Data 提供 REST API 以访问代理网络、Unlocker API 和 SERP。字段名称略有不同，但内容完全一致。 示例响应： 
"status_code": 407,
"status_message": "Proxy Authentication Required",
"error": "Proxy Authentication Required",
"error_message": "No proxy credentials provided. Please add credentials and try again.",
"error_code": "client_10010"

​
错误目录

​
HTTP 错误 400

当你在使用 Data Center / ISP 或 gIPs 产品并使用 -ip-x.x.x.x 定向标记时，如果你所在 Zone 下的 IP 因系统更新被刷新、移除或变更，就可能出现 400 错误码。
这个错误通常会在你的 Bright Data 账户最近被暂停后出现。如果账户余额变为负数，系统会自动暂停账户。如果暂停超过 24 小时，你的静态分配 IP 将会被释放。账户恢复后，重新分配的 IP 可能与之前不同，因此如果你的请求仍然指定旧的 IP，就会触发此错误。
当出现此错误时，请前往 Bright Data 的 Zones 页面，查看该 Zone 最新的可用 IP 列表。
  • x-brd-error: Proxy Error: ip_requested_not_allocated_by_customer
  • x-brd-err-msg: 请求的 IP ##.##.##.## 未分配给该 Zone。请选择分配给该 Zone 的 IP，或在代理用户名中移除 -ip 参数。
  • x-brd-error: Peer not found
  • x-brd-err-msg: 在默认国家 %Countries_list% 中未找到代理。请检查你的默认国家设置，或通过 -country 参数指定其他国家以覆盖默认设置。更多信息请查看：/cn/api-reference/proxy/geolocation-targeting
  • x-brd-error: Peer not found
  • x-brd-err-msg: 你的 [proxy type] [DC|ISP] Zone 在所选国家没有可用 IP。可能是 IP 位置变更，或该 Zone 未配置这些国家的代理。请检查 Zone 配置，并使用相关国家代码重试。更多信息：/cn/api-reference/proxy/geolocation-targeting

​
HTTP 错误 401

以下是 HTTP 401 错误对应的 x-brd-err-code 值：

​
HTTP 错误 402

以下为 HTTP 402 错误对应的 x-brd-err-code：
  • x-brd-error: Residential Failed bad_endpoint
  • x-brd-err-msg: Residential 失败 (bad_endpoint) — 请求的网站在即时 Residential（无 KYC）访问模式下不可用，因为 %HTTP_METHOD% 请求不被允许。
  如需完全 Residential 访问权限，请填写 KYC 表单：https://brightdata.com/cp/kyc
  • x-brd-error: Residential Failed bad_endpoint
  • x-brd-err-msg: 请求的网站在 Bright Data Residential 网络的即时访问模式下不可用，因为目标网站违反 robots.txt。
  如需访问权限，请参考：docs.brightdata.com/cn/proxy-networks/residential/network-access

​
HTTP 错误 403

HTTP 403 表示你正在访问一个有效 URL，但访问被禁止。服务器处理了请求，但无法返回结果，可能是请求格式错误或者被 Bright Data 策略所限制。 以下是 HTTP 403 对应的 x-brd-err-code：
  • x-brd-error: No Protocol
  • x-brd-err-msg: 请求未包含协议。请添加 HTTP 或 HTTPS 后重试。
  • x-brd-error: No Destination Host
  • x-brd-err-msg: 未指定目标主机或填写错误。请检查请求参数。
  • x-brd-error: 你正在尝试将 Browser API Zone 当成普通代理使用
  • x-brd-err-msg: Browser API Zone 必须通过浏览器访问。参考：/cn/scraping-automation/scraping-browser/introduction
  • x-brd-error: 此 super proxy 仅适用于中国域名与中国代理
  • x-brd-err-msg: 更多信息：/cn/proxy-networks/mobile/faqs#how-to-browse-chinese-sites-by-using-chinese-residentials-ips
  • x-brd-error: 目标 %HOST% 被禁止
  • x-brd-err-msg: 该域名未包含在你的 allowlist 里。请将目标加入 allowlist 或清空 allowlist 以允许全部域名。
  • x-brd-error: 目标 %HOST% 被禁止
  • x-brd-err-msg: 该域名被你的 denylist 拒绝。请从 denylist 中移除该域名或清空 denylist。
  • x-brd-error: Bad protocol
  • x-brd-err-msg: 不支持该协议。Bright Data 支持 HTTP、HTTPS、SOCKS5（须特殊申请）。
  • x-brd-error: Bad port
  • x-brd-err-msg: 端口错误。可用端口请参考：/cn/proxy-networks/faqs#how-to-see-supported-ports-and-protocols
  • x-brd-error: 禁止访问：目标站点需要特殊权限。请联系 Bright Data 支持
  • x-brd-err-msg: 禁止访问：目标站点需要特殊权限。你正在尝试访问根据我们的合规政策不被允许的目标站点。为获得访问权限，你可能需要完成 KYC 流程，可通过填写以下表格完成： https://brightdata.com/cp/kyc 。如果你已经通过 KYC，请联系你的客户经理以获取更多信息。
  • x-brd-error: 禁止访问：目标站点需要特殊权限。请联系 Bright Data 支持
  • x-brd-err-msg: 禁止访问：该目标站点为政府网站，因此需要特殊权限才能访问。你可能需要完成 KYC 流程，可通过填写以下表格提交： https://brightdata.com/cp/kyc 。如果你已经完成 KYC 审批，请联系你的客户经理以获取进一步协助。
  • x-brd-error: 禁止访问：该请求必须使用住宅代理网络
  • x-brd-err-msg: 禁止访问：你正在访问一个不允许通过 Bright Data 数据中心或 ISP 网络访问的域名。请使用 Residential（住宅）网络 zone 重试请求。
  • x-brd-error: 禁止访问：该域名在代理网络中被阻止。请通过 Unlocker API zone 或 IDE 工具获取访问权限，或联系你的客户经理协助处理
  • x-brd-err-msg: 禁止访问：该域名在数据中心、ISP 和 Residential 住宅代理网络中均被阻止。请通过 Unlocker API zone 或 IDE 工具访问，或联系你的客户经理获得进一步协助。
  • x-brd-error: 禁止访问：目标 $host 在 IPv6 协议下被 Bright Data 阻止。请尝试使用 IPv4 代理或使用 Unlocker API 访问该目标。
  • x-brd-err-msg: 禁止访问：目标 $host 在 IPv6 协议下被 Bright Data 阻止。请尝试使用 IPv4 代理或使用 Unlocker API 访问该目标。
  • x-brd-error: 禁止访问：目标被阻止
  • x-brd-err-msg: 禁止访问：你尝试访问 www.somehost.com 但被阻止。这可能与你的 denylist 或 allowlist 设置相关，或该站点不允许根据 Bright Data 的政策访问。了解更多：/cn/proxy-networks/faqs#what-is-error-code-403
  • x-brd-error: 访问被拒绝：<URL> 被分类为 <category>，并被 Bright Data 阻止
  • x-brd-err-msg: 访问被拒绝：%URL% 被分类为 %CATEGORY%，并因可能违反 Bright Data 使用政策而被阻止。详情请查看：/cn/proxy-networks/residential/network-access#residential-proxy-network-policy
  • x-brd-error: %COUNTRY% 不允许作为目标国家，请修改为其他国家
  • x-brd-err-msg: %COUNTRY% 不允许作为目标国家，请修改为其他国家
  • x-brd-error: 禁止访问：你尝试访问 %HOST% 但被阻止
  • x-brd-err-msg: 禁止访问：你尝试访问 %HOST% 但被 Bright Data 政策设置阻止。该站点可能违背 Bright Data 政策，或你的账号没有访问该站点的权限。
  • x-brd-error: 禁止访问：你尝试访问 %HOST% 但被阻止
  • x-brd-err-msg: 禁止访问：你尝试访问 %HOST% 但被 Bright Data 政策设置阻止。该站点可能违背 Bright Data 政策，或你的账号没有访问权限。
  • x-brd-error: 禁止访问：你尝试访问 %HOST% 但被阻止
  • x-brd-err-msg: 禁止访问：你尝试访问 %HOST% 但被 Bright Data 政策设置阻止。该站点可能违背政策，或你的账号没有相应权限。
  • x-brd-error: 禁止访问：你尝试访问 %HOST% 但被阻止
  • x-brd-err-msg: 禁止访问：你尝试访问 %HOST% 但被 Bright Data 政策设置阻止。该站点可能违背政策，或你的账号无访问权限。
  • x-brd-error: 禁止访问：目标 %HOST% 被阻止
  • x-brd-err-msg: 禁止访问：目标 %HOST% 被 Bright Data 阻止。该目标提供与 Bright Data 相关的服务或信息，因此无法通过 Bright Data 代理访问。如需进一步协助，请联系 [email protected]
  • x-brd-error: 禁止的主机
  • x-brd-err-msg: 目标主机根据 Bright Data 合规政策或你的账号规则配置被阻止。请在 zone 设置中检查该域名是否允许作为目标： https://brightdata.com/cp/zones/
  • x-brd-error: 代理端口 %PORT% 已被限制。请联系 Bright Data 支持 ([email protected])
  • x-brd-err-msg: 代理端口 %PORT% 已被限制。请联系 Bright Data 支持 ([email protected])
  • x-brd-error: 禁止的 SERP 域名
  • x-brd-err-msg: 目标主机根据 Bright Data 合规政策或你的账号规则配置被阻止。请在 zone 设置中检查该域名是否允许作为目标： https://brightdata.com/cp/zones/

​
HTTP 错误 407

HTTP 407 表示认证失败，可能是凭据错误，或账户被暂停。
  • x-brd-error: Authentication failed
  • x-brd-err-msg: 认证失败，请检查凭据（账户 ID、Zone 名、密码）。
  • x-brd-error: Invalid Auth
  • x-brd-err-msg: 认证无效，请检查凭据。
  • x-brd-error: Zone not found
  • x-brd-err-msg: Zone 名错误、已禁用或已删除。请确认 Zone 在控制面板中为 Active，或使用 API 查询：/cn/api-reference/account-management-api/Get_active_Zones
  • x-brd-error: Proxy Authentication Required
  • x-brd-err-msg: 未提供代理凭据，请补充后重试。
  • x-brd-error: Authentication failed
  • x-brd-err-msg: 该 IP 不允许访问 API，请检查 IP allowlist。
  • x-brd-error: IP 参数格式错误
  • x-brd-err-msg: IP 参数格式错误，请使用 x-luminati-ip header 格式。

​
HTTP 错误 429

  • x-brd-error: 请求速率过高
  • x-brd-err-msg: 你的试用账户超过速率限制。请降低请求量或完成验证流程。
  • x-brd-error: 对 %URL% 请求速率过高
  • x-brd-err-msg: 目标域名 %DOMAIN% 达到速率上限，健康监控正在限流。更多支持请联系 brightdata.com。
  • x-brd-error: 单 IP 速率过高
  • x-brd-err-msg: IP %IP% 在 Zone %ZONE% 的速率达到上限，请增加 IP 数量或降低速率。

​
HTTP 错误 502

以下是 HTTP 502 错误对应的 x-brd-err-code：
  • x-brd-error: Block direct route
  • x-brd-err-msg: 请求的直连路由被阻止。你选择了在请求失败时不通过 superproxy 重路由，因此系统阻止了重路由。更多信息请查看：/cn/api-reference/proxy/request_error_handling
  • x-brd-error: Proxy Error: We do not have proxies in the city you requested
  • x-brd-err-msg: 代理错误：你请求的城市没有可用代理。请检查城市名称拼写，或稍后重试。更多信息请查看：/cn/proxy-networks/faqs#how-to-target-a-specific-city
  • x-brd-error: Host is blocked in requested country
  • x-brd-err-msg: 目标主机在所选国家被阻止。请切换国家后重试。
  • x-brd-error: Zone has reached usage limit
  • x-brd-err-msg: 该 Zone 已达到使用限制。请前往 https://brightdata.com/cp/zones 修改或移除限制。
  • x-brd-error: Could not resolve host %HOST%
  • x-brd-err-msg: 无法解析主机 %HOST%。请检查拼写是否正确。如果拼写无误，请联系 brightdata.com 获取 DNS 支持。
  • x-brd-error: No IPv6 address (AAAA record) found for %HOST%
  • x-brd-err-msg: 无法将 %HOST% 解析为 IPv6 地址。目标主机可能未提供 IPv6 记录。请改用 IPv4 代理重试。