SERP 故障排除

调试 SERP API

使用 x-brd-debug 响应头来提取关于你的请求的详细调试信息。通过在你的代理用户名后附加 -debug-full 来激活：

curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE-debug-full:$PASSWORD@brd.superproxy.io:44445 \
  "https://www.google.com/search?q=bright+data"

x-brd-debug 响应头看起来像这样：

req_id=hl_d09913c7_a1lw123bkcg; bytes_up=2842; bytes_down=562418; billed=false; destination_ip=162.219.225.118; used_req_headers=accept-language,accept; peer_ip=r868133f79d0c3fa9d7c7ccca0151af2e; peer_country=us; render=false

字段	描述
`req_id`	内部请求 ID - 在 bug 报告中包含
`bytes_up`	处理请求时记录的出站流量
`bytes_down`	处理请求时记录的入站流量
`billed`	该请求是否被视为可计费
`destination_ip`	用于获取数据的远程服务器的 IP
`used_req_headers`	在初始请求中转发的自定义头
`peer_ip`	所用 IP 的唯一标识符 - 用于验证 IP 轮换
`peer_country`	用于该请求的对等端所在的国家/地区
`render`	结果是浏览器渲染的 HTML 还是原始 HTTP 响应

常见错误代码

错误	描述
`404`	无效的 URL - 可能已损坏或过期
`403`	URL 有效但访问被禁止
`502`	SERP API 最常见的错误 - 查看 `x-brd-error-code` 中的详细信息
`407`	凭据不正确（密码或区域名称）
`429`	速率限制 / 自动限流 - 联系支持
`401` `411` `444`	错误的请求 - 缺少头或 cookie
`503`	服务不可用 - 浏览器检查失败

示例 429 响应

HTTP/1.1 429 The request was auto-throttled due to low success rate
x-brd-error-code: sr_rate_limit
x-brd-error: The request was auto-throttled due to low success rate
date: Tue, 23 Jan 2024 17:07:19 GMT
connection: keep-alive

SERP API error catalog

Fast SERP 运行在 SERP API 内部，并共享其错误代码。当请求失败时，错误代码通过 x-brd-error-code 响应头返回，可读的错误消息通过 x-brd-error 返回，如下例所示。此目录中的所有错误均不计费。

`x-brd-error-code`	`x-brd-error`	描述
`unexpected_q`	Search query mismatch	Google 返回的结果对应的查询与您发送的查询不一致（查询被截断/伪装）。默认情况下，请求会返回此错误而不是返回不匹配的数据。如需仍接收这些数据，可启用 `return_mismatch`，并参考下文「如何检测查询截断」自行校验。

示例 query mismatch 响应

x-brd-error-code: unexpected_q
x-brd-error: Search query mismatch

HTTP Error 429

429 表示达到了速率限制。请读取错误代码以区分具体原因。

`x-brd-error-code`	`x-brd-error`	描述
`sr_rate_limit`	The request was auto-throttled due to low success rate. Please decrease your request rate to %LIMIT%/min.	按目标主机应用。该限制根据针对该主机观察到的成功率动态计算，因此会随时间变化。请将针对该主机的请求速率和并发降低到消息中给出的速率。立即重试会失败，只有在降低速率后重试才有效。未设置有效限制时，消息中不会给出具体速率。
`bucket_rate_limit`	Your system is sending too many of this type of request. If you need to send more, contact your Account Manager	按区域（zone）和账户应用，依据为其配置的请求速率。请降低请求速率以保持在配置的限制内，或联系您的客户经理提高限制。立即重试会失败。请等待 `x-brd-rate-limit-period-ms` 中给出的时间后再重试。
`failed_query_rejected`	This query recently failed and cannot be attempted at this time. Please try again later, after a minimum of 15 seconds.	按区域和查询字符串应用。该查询最近失败，因此被封禁 15 秒，立即重试同样会失败。请在至少 15 秒后重试。其他查询不受影响，可以继续以全速发送。
`repeat_query_rejected`	This query cannot be attempted at this time. Please try again later, after a minimum of 15 seconds.	按区域和查询字符串应用。同一查询在短时间内发送次数过多。请至少等待 15 秒后再重新发送该查询，并避免并发发送相同的查询。其他查询不受影响。
`client_10110`	Your account exceeded the allowed rate limits. Reduce requests rate and try again or complete the verification process to remove rate limits. You will not be charged for this request.	按账户应用，适用于未完成验证的账户。此错误由代理层返回，因此位于 `x-brd-err-code` 和 `x-brd-err-msg` 响应头中，而不是 `x-brd-error-code` 和 `x-brd-error`。请降低账户的总请求速率，或完成账户验证。

示例 failed_query_rejected 响应

x-brd-error-code: failed_query_rejected
x-brd-error: This query recently failed and cannot be attempted at this time. Please try again later, after a minimum of 15 seconds.

由于 client_10110 使用代理层响应头，处理 429 时请同时读取两组响应头：

const code = headers['x-brd-error-code'] || headers['x-brd-err-code'];

sr_rate_limit 和 bucket_rate_limit 的响应还会给出所应用的限制：

响应头	值
`x-brd-rate-limit`	达到的限制
`x-brd-rate-limit-period-ms`	该限制的统计周期（毫秒）

如何检测查询截断

Google 有时会返回比你提交的查询更短版本的结果。例如，搜索 pizza in tlv 可能返回 pizza 的结果。此行为同时适用于 SERP API 和 Fast SERP 文本（网页）搜索。在解析后的响应中比较 general.query 与 general.detected_query，然后检查是否存在 spelling 对象，以区分真正的拼写更正和被截断的搜索：

如果 general.query 与 general.detected_query 相同，说明 Google 搜索的正是你提交的内容。
如果二者不同，请检查是否存在 spelling 对象：
- 存在 spelling - Google 自动更正了拼写，结果对更正后的查询有效。
- 不存在 spelling - Google 截断（cloaked）了你的查询，结果对应的是你所搜索内容的更短版本。

下例展示了一个自动更正的查询，其中 detected_query 与 query 不同，但 spelling 对象确认结果有效：

{
  "general": {
    "query": "pizaa",
    "detected_query": "pizza"
  },
  "spelling": {
    "original_text": "pizaa",
    "original_link": "https://www.google.com/search?q=pizaa&nfpr=1",
    "auto_corrected_text": "pizza",
    "auto_corrected_link": "https://www.google.com/search?q=pizza&spell=1"
  },
  "organic": [ ... ]
}

有关 general 和 spelling 字段定义，SERP API 参见解析后的 JSON 结果，Fast SERP 参见 Fast SERP 网页搜索。

查询被拦截时会发生什么

当 Bright Data 检测到 Google 标记了某个查询时，该查询会在 SERP API 和 Fast SERP 中被拦截 15 秒。在此时间窗口内针对同一查询的任何请求都会返回 failed_query_rejected 错误（如查询因重复过于频繁而被限流，则返回 repeat_query_rejected）。请在 15 秒窗口结束后重试该查询，或更改查询内容，以获取结果。完整的错误响应参见 SERP API 错误目录。

获取每个域名的成功率统计

从过去 7 天检索 SERP API 成功率统计。支持单个域名或通配符。

单个域名

curl "https://api.brightdata.com/unblocker/success_rate/google.com" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY"

所有监控的 TLD

curl "https://api.brightdata.com/unblocker/success_rate/google.*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY"

提供 API 密钥后，请相应地替换所有 $API_KEY、$CUSTOMER_ID、$ZONE 和 $PASSWORD 占位符。

Introduction

Getting Started

调试 SERP API

常见错误代码

SERP API error catalog

HTTP Error 429

如何检测查询截断

查询被拦截时会发生什么

获取每个域名的成功率统计

​调试 SERP API

​常见错误代码

​SERP API error catalog

​HTTP Error 429

​如何检测查询截断

​查询被拦截时会发生什么

​获取每个域名的成功率统计

调试 SERP API

常见错误代码

SERP API error catalog

HTTP Error 429

如何检测查询截断

查询被拦截时会发生什么

获取每个域名的成功率统计