# 错误与页面状态：哪里失败了，以及是否该重试

> 搜索 API 错误：六个 HTTP 错误码（从不收费）、200 响应内的页面状态，以及何时用退避策略重试。无需 KYC，加密货币支付。

- URL: https://llmwebsearch.com/zh/docs/errors/
- 最后更新: 2026-10-22
- 发布者: LLMWebSearch (https://llmwebsearch.com)

存在两类问题。HTTP 错误表示整个调用失败，不产生任何费用。页面状态表示搜索成功但某个页面无法读取；它出现在正常的 200 响应里。Agent 应分别以不同方式处理两者。

**快速回答 — LLMWebSearch API 会返回哪些错误，会收费吗？**

**LLMWebSearch** 有六个 HTTP 错误：`400 invalid_parameter`、`401 invalid_api_key`、`402 insufficient_credits`、`429 rate_limited`、`502 search_failed` 和 `504 search_timeout`。均不收费。无法读取的页面会在 200 响应内显示 `content_status`。成功完成一次搜索消耗 1 积分，低至 US$1.20/千次搜索（截至 2026 年 10 月）。无需 KYC；加密货币支付。

## 有哪些 HTTP 错误？

响应体始终为 `{"error": {"code": "…", "message": "…"}}`。任何错误都不消耗积分。

| HTTP | `code` | 原因 | 是否重试？ |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | 缺少必需参数或值超出范围 | 否：修正请求 |
| 401 | `invalid_api_key` | 密钥缺失、错误或已撤销 | 否：检查密钥 |
| 402 | `insufficient_credits` | 余额不足以支付本次调用 | 否：购买积分包 |
| 429 | `rate_limited` | 每分钟调用次数超过账户允许上限 | 是，稍等片刻后重试 |
| 502 | `search_failed` | 搜索无法完成 | 是，用退避策略重试 |
| 504 | `search_timeout` | 30 秒内没有搜索结果 | 是，用退避策略重试 |

## 页面状态与错误有何不同？

页面状态描述的是单个结果，而不是整个调用。搜索已执行，结果也在，`credits_used` 照常设置。只是那一页的内容缺失，`content_status` 会说明原因：`blocked_by_robots`、`blocked_by_site_policy`、`target_refused`、`fetch_failed`、`fetch_timeout` 或 `unsupported_content`。

不要把这些当作失败而重试整个搜索。请使用其他结果、缺失页面的摘要，或换一个来源。[响应格式](https://llmwebsearch.com/zh/docs/response/)页面用表格解释了每种状态。

## 为什么你们从不绕过拒绝进行重试？

因为拒绝就是网站的答复，我们尊重它。我们的读取器遵守 robots.txt：它会以 LLMWebSearch 表明身份，遵守网站为它或为所有机器人写下的规则，并排除任何它无权读取的页面内容。在 robots.txt 中设置 Content-Signal: ai-input=no 的网站，其页面内容不会出现在你的结果中。当网站以 403、429 或验证页拒绝我们的读取器时，我们会将其报告为 `target_refused`，并在 `target_status` 中给出网站的状态。

当网站拒绝我们的读取器时，结果会不带内容返回，并附上该网站的状态：我们绝不破解 CAPTCHA、不登录账户，也不绕过封锁或付费墙。我们也不会用另一个身份或伪装的浏览器重试。你的 agent 不应在这样的页面上循环：结果不会改变，而且网站已经说了不。

## 我的代码应该在什么时候重试？

仅在 `429`、`502` 和 `504` 时重试。等待，然后重试，每次将等待时间加倍，并加入一些随机性，以免并行 worker 同步重试。三到五次尝试就足够；之后报告失败。

绝不要重试 `400`、`401` 或 `402`：除非你改变某些东西，否则相同的请求会得到相同的答复。对于页面，`fetch_failed` 和 `fetch_timeout` 可能稍后通过新的搜索或 `/extract` 调用成功。`target_refused`、`blocked_by_robots` 和 `blocked_by_site_policy` 是最终结果。

*Python：对 429、502 和 504 使用指数退避重试*

```python
import os
import random
import time

import requests

API = "https://llmwebsearch.com/api/v1/search"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
RETRY_ON = {429, 502, 504}


def search(body, attempts=5):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
        if resp.status_code == 200:
            return resp.json()
        err = resp.json().get("error", {})
        if resp.status_code not in RETRY_ON or attempt == attempts:
            raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, 30)


data = search({"q": "how to rotate api keys without downtime"})
unread = [r["url"] for r in data["results"] if r["content_status"] not in ("ok", "not_requested")]
print("credits:", data["credits_used"], "| pages not read:", unread)

```

## 遇到 402 insufficient_credits 该怎么办？

停止并充值。该调用未执行，也没有花费。为避免在长时间任务中途停止，请先用 `GET https://llmwebsearch.com/api/v1/credits` 检查余额（免费），并与你计划的搜索次数进行比较。请记住，`read` 大于 3 的搜索需要 2 个积分。

积分来自用你的加密货币余额购买的积分包。查询积分永不过期：这个月没用完的，明年还在。

## 如何保持在速率限制之下？

在你自己的代码中限制同时运行的调用数量。每个账户都有每分钟调用上限，显示在控制面板中；联系支持即可提高。一个小的并行 worker 池（对大多数 agent 来说四到八个）可以保持稳定节奏而不产生突发。[Python](https://llmwebsearch.com/zh/docs/python/) 和 [Node.js](https://llmwebsearch.com/zh/docs/node/) 页面都展示了这样的池。

当你确实收到 `429` 时，在下一次尝试前暂停，而不是立即发出。立即重试只会增加更多被拒绝的调用。

## 错误：常见问题

### 所有页面都被拒绝的搜索仍然消耗一个积分吗？

是的，如果搜索本身成功：你仍然会获得排序后的结果和摘要。搜索的价格不取决于有多少页面能被读取。

### 401 是由密钥被撤销引起的吗？

可能是。密钥被撤销、拼写错误、缺少 `Bearer ` 前缀，或 header 从未到达我们这里，都会导致 `401 invalid_api_key`。为每个 agent、应用或团队成员各建一个 API 密钥，并可在控制面板中吊销其中任意一个，而不影响其他密钥。

### 为什么页面返回 fetch_timeout？

页面是并行读取的，耗时超过 15 秒的页面会在没有内容的情况下返回，以免拖慢整个答复。慢速网站有时会在后续尝试中响应。

### 我能查看失败的调用吗？

可以。仪表板历史记录会列出你 30 天内的调用，包括失败的调用，以及它们的状态和积分。失败的调用显示 0 积分。

---

LLMWebSearch: LLMWebSearch 是一款面向 AI 智能体的网页搜索 API，返回排序后的搜索结果，并附带热门页面的 Markdown 格式内容，采用加密货币支付，无需上传证件。预付费积分低至 US$1.20/千次搜索，永不过期。无 KYC——无需证件、无需自拍、无需提交任何文件。加密货币支付。