HTTP `429 Too Many Requests` 表示：**Wikipedia/Wikimedia 认为你的 Node.js 应用在一段时间内发送了过多请求，因此暂时进行了限流。**

对于 Node.js 程序，最常见的原因并不只是“请求次数绝对很多”，而是下面几种因素叠加。

## 一、最可能的原因：没有设置合规的 `User-Agent`

Wikimedia 要求自动化程序发送一个**有意义、可识别并包含联系方式**的 `User-Agent`，例如：

```text
JerryWikipediaReader/1.0 (https://example.com/contact; developer@example.com)
```

不要只使用下面这类通用值：

```text
node
fetch
axios
curl
Mozilla/5.0
```

Wikimedia 官方明确说明，没有发送描述性 `User-Agent`，或者使用空白、通用的 `User-Agent`，可能被限制或阻止；同时也明确反对自动化程序伪装成普通浏览器。([Wikimedia Foundation][1])

更重要的是，Wikimedia 当前公布的 API 限流分类中：

| 请求身份                      |   公布的参考限制 |
| ------------------------- | --------: |
| 只能通过 IP 识别的请求             |   10 次/分钟 |
| 带合规 `User-Agent` 的匿名机器人请求 |  200 次/分钟 |
| 未登录的浏览器请求                 |  200 次/分钟 |
| 普通已认证请求                   |  200 次/分钟 |
| 资深编辑者的已认证请求               | 2000 次/分钟 |

这些数字是 API 网关层面的概览，具体接口和运行状态仍可能有额外限制。([MediaWiki][2])

因此，假设你的 Node.js 应用没有设置明确的 `User-Agent`，即使一分钟只调用十几次，也有可能被归入“未识别客户端”，从而很快收到 `429`。

需要注意：缺少合规 `User-Agent` 并不一定只返回 `429`。在某些策略或端点上，也可能返回 `403 Forbidden`。([Wikimedia Foundation][1])

---

## 二、使用了大量并发请求

下面这种代码很容易触发限流：

```javascript
const results = await Promise.all(
  titles.map(title => fetch(createUrl(title)))
);
```

假设 `titles` 有 500 个元素，程序会在很短时间内发出大量并行请求。即使一分钟总量看起来不是特别夸张，瞬间并发也可能被判定为异常流量。

Wikimedia 当前建议将并发请求数量控制在 **3 个或更少**，并在可能的情况下串行发送请求。([MediaWiki][2])

---

## 三、没有处理 `Retry-After`

当 Wikimedia 返回 `429` 时，通常会带有：

```http
Retry-After: 10
```

它的含义是：

> 至少等待 10 秒后再重试。

有些程序一收到 `429` 就立即重试：

```javascript
while (!response.ok) {
  response = await fetch(url);
}
```

这会形成恶性循环：

```text
请求过快
  ↓
收到 429
  ↓
立即重试
  ↓
请求更密集
  ↓
限流时间进一步延长
```

Wikimedia 官方要求客户端尊重 `Retry-After`；如果响应中没有该字段，应至少等待 5 秒，或者使用指数退避策略。([MediaWiki][2])

---

## 四、你的服务器使用了共享出口 IP

限流往往不只是按某个 Node.js 进程计算，还可能涉及：

* 出口 IP；
* `User-Agent`；
* 是否登录或认证；
* API 访问身份；
* 请求端点；
* 请求行为模式。

假设你的程序运行在以下环境：

* 云函数；
* 公共代理；
* Docker 托管平台；
* 公司统一 NAT；
* GitHub Actions；
* Serverless 平台；
* 免费云主机。

那么多个用户或多个应用可能共用同一个出口 IP。即使你的程序只发了少量请求，其他程序也可能已经消耗了这个 IP 的额度。

这是收到“偶发 429”，尤其是程序刚启动便收到 `429` 时，一个很常见的可能原因。Wikimedia 公布的“未识别请求”本身就是主要以 IP 作为识别特征。([MediaWiki][2])

---

## 五、反复读取相同页面，没有缓存

例如每次用户打开页面，你的后端都重新访问 Wikipedia：

```text
用户 A 请求北京词条 → 请求 Wikipedia
用户 B 请求北京词条 → 再请求 Wikipedia
用户 C 请求北京词条 → 又请求 Wikipedia
```

实际上，北京词条的结果通常可以缓存几分钟甚至更久。

Wikimedia 的 API 使用规范建议：对于可以缓存的数据，不要反复请求相同内容；读取数据时应尽量使用可缓存的 `GET` 请求。([MediaWiki][3])

可以采用：

* 内存缓存；
* Redis；
* 本地文件缓存；
* 数据库缓存；
* CDN；
* 条件请求，例如 `ETag` 和 `If-None-Match`。

---

## 六、直接抓取 HTML 页面，而不是使用 Wikimedia API

例如直接请求：

```text
https://en.wikipedia.org/wiki/Node.js
```

然后再使用 `cheerio` 解析整个 HTML。

这种方式并非绝对禁止，但如果你的真实需求只是获取：

* 页面标题；
* 摘要；
* 正文；
* 页面 ID；
* 修订版本；
* 分类；
* 图片；
* 链接；

通常应该优先考虑官方 API。

Wikimedia 官方提供多类 API，包括：

* MediaWiki REST API；
* MediaWiki Action API；
* Wikimedia REST API；
* Analytics API；
* 页面描述和摘要相关 API。

对于批量或结构化访问，API 通常比抓取完整 HTML 页面更合适。([MediaWiki][4])

不过，即使改用 API，也仍然必须遵守 `User-Agent`、并发数、缓存和重试规范。

---

# 推荐的 Node.js 实现

下面这个示例适用于支持全局 `fetch` 的现代 Node.js 环境。

```javascript
const USER_AGENT =
  "JerryWikipediaReader/1.0 " +
  "(https://example.com/wikipedia-reader; developer@example.com)";

/**
 * 解析 Retry-After。
 *
 * Retry-After 可能是：
 *   Retry-After: 10
 *
 * 也可能是：
 *   Retry-After: Wed, 22 Jul 2026 10:00:00 GMT
 */
function parseRetryAfter(value) {
  if (!value) {
    return null;
  }

  const seconds = Number(value);

  if (Number.isFinite(seconds)) {
    return Math.max(0, seconds * 1000);
  }

  const retryDate = Date.parse(value);

  if (Number.isFinite(retryDate)) {
    return Math.max(0, retryDate - Date.now());
  }

  return null;
}

function sleep(milliseconds) {
  return new Promise(resolve => setTimeout(resolve, milliseconds));
}

/**
 * 请求 Wikipedia，并对 429 和 503 执行退避重试。
 */
async function fetchWikipedia(url, options = {}) {
  const {
    maxRetries = 5,
    timeoutMs = 15_000,
  } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);

    try {
      const response = await fetch(url, {
        method: "GET",
        redirect: "follow",
        signal: controller.signal,
        headers: {
          "User-Agent": USER_AGENT,
          "Accept": "application/json, text/html;q=0.9",
        },
      });

      if (response.ok) {
        return response;
      }

      const retryable =
        response.status === 429 ||
        response.status === 503;

      if (!retryable || attempt === maxRetries) {
        const responseBody = await response.text();

        throw new Error(
          `Wikipedia request failed: ` +
          `${response.status} ${response.statusText}\n` +
          responseBody.slice(0, 500)
        );
      }

      const retryAfterValue = response.headers.get("retry-after");
      const retryAfterMs = parseRetryAfter(retryAfterValue);

      // 没有 Retry-After 时使用指数退避：
      // 5 秒、10 秒、20 秒、40 秒……
      const exponentialBackoffMs =
        Math.min(60_000, 5_000 * 2 ** attempt);

      // 添加少量随机抖动，避免多个进程同时重试。
      const jitterMs = Math.floor(Math.random() * 1_000);

      const waitMs =
        retryAfterMs ?? exponentialBackoffMs + jitterMs;

      console.warn(
        `Wikipedia returned ${response.status}. ` +
        `Retrying in ${waitMs} ms. ` +
        `Attempt ${attempt + 1}/${maxRetries}.`
      );

      await sleep(waitMs);
    } finally {
      clearTimeout(timeoutId);
    }
  }

  throw new Error("Unexpected retry loop termination.");
}
```

调用示例：

```javascript
async function main() {
  const url =
    "https://en.wikipedia.org/w/rest.php/v1/page/Node.js";

  const response = await fetchWikipedia(url);
  const data = await response.json();

  console.log(data);
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});
```

请把示例中的联系方式替换为你自己的有效联系方式：

```javascript
const USER_AGENT =
  "YourApplicationName/1.0 " +
  "(https://your-domain.example/contact; your-email@example.com)";
```

联系方式不一定非要同时包含网站和邮箱，至少提供一种可联系到维护者的方式即可。

---

# 如果使用 Axios

可以首先这样设置：

```javascript
import axios from "axios";

const wikipediaClient = axios.create({
  timeout: 15_000,
  headers: {
    "User-Agent":
      "JerryWikipediaReader/1.0 " +
      "(https://example.com/contact; developer@example.com)",
    "Accept": "application/json",
  },
});

const response = await wikipediaClient.get(
  "https://en.wikipedia.org/w/rest.php/v1/page/Node.js"
);

console.log(response.data);
```

但设置 `User-Agent` 只能解决“客户端无法被正确识别”的问题，不能取代：

* 并发控制；
* `Retry-After`；
* 指数退避；
* 缓存；
* 批量请求合并。

---

# 限制并发数量

不要一次性执行几百个 `Promise.all` 请求。可以安装 `p-limit`：

```bash
npm install p-limit
```

然后把并发控制在 3：

```javascript
import pLimit from "p-limit";

const limit = pLimit(3);

const titles = [
  "Node.js",
  "JavaScript",
  "TypeScript",
  "React",
  "Angular",
];

const tasks = titles.map(title =>
  limit(async () => {
    const encodedTitle = encodeURIComponent(title);

    const url =
      `https://en.wikipedia.org/w/rest.php/v1/page/${encodedTitle}`;

    const response = await fetchWikipedia(url);
    return response.json();
  })
);

const pages = await Promise.all(tasks);

console.log(pages);
```

在大量批处理场景下，除了控制并发，最好再在请求之间加入适当间隔。

---

# 如何快速定位你的具体原因

在程序中打印以下信息：

```javascript
console.log({
  status: response.status,
  retryAfter: response.headers.get("retry-after"),
  userAgentSent: USER_AGENT,
  url: response.url,
});
```

然后重点检查：

1. 请求是否设置了描述性的 `User-Agent`；
2. 一分钟实际发送了多少次请求；
3. 瞬间并发数是多少；
4. 是否使用了无限重试；
5. 是否无视了 `Retry-After`；
6. 是否反复读取同一页面；
7. 是否运行在共享出口 IP 环境；
8. 请求的是普通 HTML 页面、Action API，还是 REST API。

## 结论

你遇到 `429` 的直接原因是 **Wikimedia 的限流系统认为当前客户端的请求速率或行为超过了允许范围**。

对于 Node.js 应用，优先修改这四项，通常就能解决：

```text
设置可识别的 User-Agent
        +
并发数量不超过 3
        +
遵守 Retry-After 并使用指数退避
        +
缓存重复读取的页面
```

其中，**没有设置合规 `User-Agent`** 很可能是首要排查项，因为它可能使你的请求只能通过 IP 识别，从而落入明显更低的限流等级。

[1]: https://foundation.wikimedia.org/wiki/Policy%3AWikimedia_Foundation_User-Agent_Policy "Policy:Wikimedia Foundation User-Agent Policy - Wikimedia Foundation Governance Wiki"
[2]: https://www.mediawiki.org/wiki/Wikimedia_APIs/Rate_limits "Wikimedia APIs/Rate limits - MediaWiki"
[3]: https://www.mediawiki.org/wiki/API%3AEtiquette "API:Etiquette - MediaWiki"
[4]: https://www.mediawiki.org/wiki/Wikimedia_APIs "Wikimedia APIs - MediaWiki"


HTTP 429 Too Many Requests 表示：Wikipedia/Wikimedia 认为你的 Node.js 应用在一段时间内发送了过多请求，因此暂时进行了限流。

HTTP 429 Too Many Requests 的处理办法

紫薇堂堂主

人工智能

Node.js应用访问Wikipedia时遇到HTTP 429错误？主要因未设置合规User-Agent、并发请求过高、未处理Retry-After头、共享IP限制或重复请求未缓存。解决方案：设置包含联系方式的User-Agent、控制并发数在3以内、实现指数退避重试机制、合理缓存数据。遵循Wikimedia API规范可有效避免限流问题。

代码解释

TypeScript 

云主机

服务器

云函数

数据库

Redis

Agent

ReAct 

CDN免费试用


让每一个 Agent，都跑在云上

cngw

serverless-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Node.js应用访问Wikipedia时遇到HTTP 429错误？主要因未设置合规User-Agent、并发请求过高、未处理Retry-After头、共享IP限制或重复请求未缓存。解决方案：设置包含联系方式的User-Agent、控制并发数在3以内、实现指数退避重试机制、合理缓存数据。遵循Wikimedia API规...

HTTP 429 Too Many Requests 的处理办法-腾讯云开发者社区-腾讯云

HTTP 429 Too Many Requests 的处理办法

HTTP 429 Too Many Requests 的处理办法

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐