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

# Business Search 错误处理

> 处理 Business Search 错误。先读 HTTP 状态码，修正 HTTP 400 校验消息，并只对 3 类瞬时故障进行重试。

Business Search 的错误是一个带有 `error` 消息的 JSON 响应体，绝不是零匹配的成功搜索。HTTP 200 且 `documents` 为空数组表示搜索已执行但没有结果；其他状态码都会说明出了什么问题。

## Business Search 会返回哪些状态码

| 状态码   | 含义                     | 触发原因                                                                                                                                                     |
| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | 搜索已执行                  | `documents` 仍可能为空                                                                                                                                        |
| `400` | 请求体无效                  | 未知类目，无效的 `mode`、`query`、`view`、`offset` 或 `limit`，未知的视图配置名，`view` 中包含未知字段名，自然语言查询超过 200 个字符，字段类型不支持所用的运算符（例如对文本字段使用 `equals`），或账户无法发送的调试属性（例如 `explain`） |
| `401` | API key 缺失、无效或已过期      | key 错误会返回 `{"error":"Invalid token"}`，令牌过期则返回 `Token expired`                                                                                            |
| `403` | 账户无法使用 Business Search | 该 key 没有对应的客户账户，账户处于非激活状态，或账户不在 API 允许列表中                                                                                                                |
| `404` | 未知的 API 版本             | 路径中的版本段无法识别                                                                                                                                              |
| `500` | 服务端配置或后端错误             | 使用有上限的退避重试                                                                                                                                               |
| `429` | 超出速率限制                 | 该类目与模式下的请求过多。该请求未执行搜索，也不会计费                                                                                                                              |
| `501` | 请求有效但不受支持              | 数据源被禁用或不可用，或该数据源不支持自然语言规划或排序                                                                                                                             |
| `502` | 自然语言处理环节失败             | 规划器或排序步骤返回了无效或空响应，适用于 `instant` 和 `smart`                                                                                                                |
| `504` | 搜索超时                   | 使用有上限的退避重试                                                                                                                                               |

请在 `429` 响应的 `Retry-After` 标头指定的等待时间之后重试。请对 `500`、`502` 和 `504` 使用有上限的退避重试。切勿重试 `400`、`401`、`403`、`404` 或 `501`，因为同样的请求每次都会失败。如果同一请求反复返回带有 `error_code` `backend_search_failed` 的 `500`，问题出在请求本身，请修改请求而不是重试。

## 请求为什么被拒绝

Business Search 以 HTTP 400 拒绝无效请求体，并在响应中说明被拒绝的内容。选择未知输出字段时会返回：

```json theme={null}
{
  "error": "view: unknown field(s): not_a_released_field"
}
```

字段类型不支持所用运算符时会以同样方式被拒绝。错误信息会指出字段、运算符以及该运算符支持的类型：

```json theme={null}
{
  "error": "Invalid query: In operator 'equals', field 'industry': Operator does not support field type 'text'. Supported types: bool, byte, double, float, int, language, long, string."
}
```

`industry`、`current_title` 等文本字段只接受 `text` 运算符。参见 [Business Search 查询语法](/cn/products/business-search/query-syntax)。

部分拒绝响应还会包含 `error_code`，即机器可读的错误类别，例如 `invalid_query` 或 `backend_search_failed`。存在 `error_code` 时可据此分支处理，不存在时请回退到 HTTP 状态码，因为通用错误不包含该字段。

校验失败时请修正请求。速率限制检查在校验之后执行，因此被拒绝的请求不会消耗速率限制配额，但重复发送无效请求体同样无法成功。

## 速率限制是多少

默认限制为每分钟 60 次请求，按账户、类目和模式分别计算。因此公司搜索与人物搜索各有独立配额，每个类目下的 Ludicrous、Instant 和 Smart 也各有独立配额。

超过限制时，Business Search 会返回 HTTP 429，并在 `Retry-After` 标头中给出需要等待的秒数。请等待该时长后再重试。被限流的请求不会执行搜索，也不会计费。

## 各类故障应如何处理

| 故障                        | 含义                                 | 处理方式                                                                           |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------ |
| HTTP 400                  | 请求体无效                              | 修正 `error` 中指出的字段、运算符、模式或分页值                                                   |
| HTTP 401 或 403            | key 有误或已过期，或账户无法使用 Business Search | 在[控制面板](https://brightdata.com/cp/setting/users)中检查 key，并确认 Business Search 权限 |
| HTTP 429                  | 超出速率限制                             | 等待 `Retry-After` 给出的秒数，然后重新发送请求                                                |
| HTTP 500、502 或 504        | 请求稍后可能成功                           | 使用有上限的退避重试，绝不使用无限重试循环                                                          |
| HTTP 200 且 `documents` 为空 | 搜索已执行但没有匹配                         | 视为无匹配结果，既不是错误，也不能证明该实体不存在                                                      |

请在自己的日志中区分这四种情况。把它们合并成单一的“搜索失败”分支，会掩盖查询错误与服务故障之间的区别。

## 联系 Bright Data 支持时应提供什么

请提供端点、HTTP 状态码、请求时间、错误消息，以及返回的 `req_id`。必要时可附上脱敏后的请求体。

<Warning>
  切勿把 API key 或 `Authorization` 请求头发送给支持团队，无论是在工单、日志导出还是截图中。一旦泄露，请立即轮换该 key。
</Warning>

## 常见问题

### 返回 200 是否表示查询被正确理解

不是。200 表示搜索已执行。在 Instant 和 Smart 模式下，自然语言意图和结果相关性不会因为 HTTP 请求成功而得到保证，因此使用记录前请先审阅结果。

### HTTP 400 应该重试吗

不应该。HTTP 400 表示请求本身无效，同样的请求体每次都会失败。只对 HTTP 500、502 和 504 进行有上限的退避重试。

### 被拒绝的请求会计入速率限制吗

不会。Business Search 先校验请求，再检查速率限制，因此格式错误的查询不会消耗配额。请修正请求而不是重试，因为无效请求体无论发送多少次都不会成功。

### 如何区分字段缺失与空结果

返回记录中缺少某个字段，表示数据源对该记录没有存储值。`documents` 数组为空，表示没有记录匹配条件。前者按记录处理，后者按请求处理。