解读 RPC 速率限制响应头：X-RateLimit 与 Retry-After

为什么仅靠被动处理 429 还不够

大多数 RPC 客户端只有在请求因 HTTP 429 失败时才会意识到速率限制。这是一条代价高昂的路径：被限流的调用仍然消耗了一次网络往返，仍然增加了你的 p99 延迟，而且在许多提供商那里仍然会计入更严格的窗口，因此一连串 429 可能会延长惩罚。 如何修复 RPC 429 错误 手册涵盖了被动侧——带抖动的指数退避——但仅靠退避只是在猜测。

速率限制响应头是同一契约的主动侧。服务器不是让你从失败中推断预算，而是在每个响应中告诉你还剩多少配额以及何时重置。读取这些字段的客户端可以在第一个 429 出现之前就放慢速度、推迟非紧急工作或分散突发流量。

这对延迟敏感的路径最为重要。如果你的应用按计划轮询账户状态或提交交易，一次 429 就可能让整批任务错过截止时间。读取响应头让你可以用一个小的、可控的延迟换取避免一个大的、不可控的延迟。

• 一次 429 会消耗一次往返，而且通常会计入比你正在调整节奏的窗口更严格的窗口。
• 响应头让你在达到限制之前调整节奏，而不是之后。
• 主动调整节奏保护 p99 延迟；被动退避只保护正确性。

两大响应头家族：IETF RateLimit 与旧版 X-RateLimit

实际中存在两个命名家族。第一个是 IETF 草案 HTTP RateLimit Header Fields，它将 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset 定义为结构化字段。第二个是较旧的事实标准 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset，由早期公共 API 推广，至今仍被 RPC 提供商广泛使用。

两个家族的语义相同：Limit 是当前窗口的上限，Remaining 是该上限还剩多少，Reset 是窗口何时滚动。区别在于命名，有时还在于 Reset 的单位。由于响应头的存在性和命名因提供商而异，健壮的客户端应在每个响应中检查两个家族，而不是假定其中一个。

Retry-After 是 RFC 9110（HTTP 语义）中定义的另一个更早的字段。它最常随 429 或 503 一起发送，告诉你重试前需要等待多久。它不是预算信号——它是一条指令。

• IETF 草案家族：RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset。
• 旧版家族：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。
• Retry-After（RFC 9110）是随 429/503 发送的指令，不是预算字段。

不靠猜测解析 Reset 和 Retry-After

最常见的解析错误是假定 Reset 的单位。有些提供商发送 epoch 秒（如 1757800000 这样的大数字）；另一些发送增量秒（如 12 这样的小数字）。你可以通过数量级来检测形式：大约大于 1e9 的值几乎肯定是 epoch 秒，而小值是增量。在使用之前，始终将其转换为绝对截止时间。

RFC 9110 定义 Retry-After 接受增量秒或 HTTP 日期。像 30 这样的值表示等待 30 秒；像 Wed, 21 Oct 2026 07:28:00 GMT 这样的值表示等到那个时刻。两者都要解析：如果值全是数字，按秒处理；否则按日期解析并减去当前时间。

将 429 的 Retry-After 视为优先于你自己的退避。如果服务器说等待 30 秒，等待 2 秒后重试只会再消耗一次请求，并可能延长惩罚。只有在 Retry-After 缺失时才回退到你自己的指数退避。

• Reset：通过数量级检测 epoch 还是增量，然后转换为绝对截止时间。
• Retry-After：数字表示秒；其他任何内容都是 HTTP 日期。
• 存在服务器 Retry-After 时，它优先于客户端退避。

响应头取值的决策表

在根据响应头取值采取行动之前，用此表判断其含义。目标是将每种形式归一化为两个数字：剩余预算和距离重置的秒数。

归一化后，你的节奏控制逻辑只需要这两个数字加上当前时间。这使客户端保持简单且与提供商无关。

• RateLimit-Remaining = 0，Reset 在 5 秒后 → 暂停所有非紧急调用 5 秒，然后恢复。
• RateLimit-Remaining = 5，Reset 在 1 秒后 → 现在可以安全地发送小突发；窗口即将滚动。
• RateLimit-Remaining = 5，Reset 在 60 秒后 → 将这 5 次调用分散到 60 秒内；不要突发。
• Retry-After = 30 → 精确等待 30 秒，无论你自己的退避计划如何。
• Retry-After = HTTP 日期 → 等到那个时刻，计算为日期减去当前时间。
• 完全没有响应头 → 回退到保守的固定节奏，并测量你自己的上限。

为什么窗口模型会改变 Remaining 的含义

Remaining = 5 在每种限流器下含义并不相同。在固定窗口下，计数器在边界处重置，因此在边界前刚好放下的突发是免费的。在滑动窗口下，计数器持续反映最近 N 秒，因此即使 Remaining 看起来健康，同样的突发仍可能被限流。

令牌桶限流器又不同：它们以稳定速率补充，并允许最多达到桶大小的突发。只读取 Remaining 的客户端无法区分这些模型，这就是为什么 Reset 值和 Remaining 值同样重要。如果 Reset 很远而 Remaining 很低，你接近硬上限；如果 Reset 很近，窗口即将刷新。

实用规则：根据 Remaining 和 Reset 推导出可持续速率并据此调整节奏，永远不要仅仅因为 Remaining 非零就假定突发是安全的。要深入了解限制如何与延迟相互作用，请参阅 如何降低 RPC 延迟。

• 固定窗口：边界附近的突发很便宜。
• 滑动窗口：突发被平滑；Remaining 可能看起来健康但仍会被限流。
• 令牌桶：稳定补充加上最多达到桶大小的突发配额。

构建预算感知客户端

预算感知客户端在每个响应上做三件事：读取响应头、计算可持续速率、调整下一次调用的节奏。可持续速率就是 Remaining 除以距离 Reset 的秒数。如果该速率低于你的工作负载所需，就推迟非紧急调用，而不是发送它们并收集 429。

对于突发，在你的 RPC 调用前使用令牌桶或漏桶限速器。限速器以可持续速率释放请求，并吸收短时尖峰而不超出预算。当 429 带着 Retry-After 到达时，限速器应排空并等待完整间隔后再释放任何请求。

这种设计还使故障转移更清晰。如果你运行多个端点，每个都有自己的预算；按端点跟踪 Remaining 的客户端可以将负载转移到有余量的端点。 RPC 节点监控与故障转移 指南涵盖了该模式的健康检查方面。

• 可持续速率 = Remaining / 距离 Reset 的秒数。
• 使用令牌桶或漏桶限速器来分散突发。
• 按端点跟踪预算，以便故障转移优先选择有余量的端点。

你消耗的是哪个预算？按密钥、按 IP、按方法、按连接

响应头告诉你还剩多少预算，但不总是告诉你哪个预算。提供商可能按 API 密钥、按源 IP、按方法权重或按连接进行限制。像 eth_getLogs 这样的重方法可能比 eth_blockNumber 这样的轻方法花费更多，因此单个 Remaining 计数器可能掩盖方法级权重。

如果你在多个服务间共享 API 密钥，一个嘈杂的服务可能耗尽所有服务的预算。如果你在 NAT 或代理后共享 IP，你的预算可能与其他无关流量合并计算。了解你消耗的是哪个维度，有助于决定是拆分密钥、添加专用端点，还是将重方法移到单独路径。

有关提供商特定的限制和套餐详情，请参阅 RPC 定价 和 API 服务 页面。响应头的存在性和命名因提供商而异。

• 按密钥：使用该密钥的所有服务共享。
• 按 IP：在 NAT 或代理后合并计算。
• 按方法权重：重调用比轻调用花费更多。
• 按连接：WebSocket 连接可能独立于请求预算受到限制。

可运行的 Node.js 示例：记录响应头并调整下一次调用的节奏

此示例使用 Node.js 18+ 内置的 fetch。它读取两个响应头家族，归一化 Reset，并在预算低时等待后再进行下一次调用。它还会在 429 时遵循 Retry-After。

针对你自己的端点运行它，并观察记录的值。你看到的数字是你端点的真实行为，而不是基准测试。

// node --version >= 18
const RPC_URL = process.env.RPC_URL || 'https://your-endpoint.example';

function parseReset(value) {
  if (!value) return null;
  const n = Number(value);
  if (!Number.isFinite(n)) return null;
  // epoch seconds are large; delta seconds are small
  return n > 1e9 ? n * 1000 : Date.now() + n * 1000;
}

function readBudget(headers) {
  const get = (names) => {
    for (const name of names) {
      const v = headers.get(name);
      if (v !== null) return v;
    }
    return null;
  };
  const limit = get(['ratelimit-limit', 'x-ratelimit-limit']);
  const remaining = get(['ratelimit-remaining', 'x-ratelimit-remaining']);
  const reset = get(['ratelimit-reset', 'x-ratelimit-reset']);
  return {
    limit: limit ? Number(limit) : null,
    remaining: remaining ? Number(remaining) : null,
    resetAt: parseReset(reset),
  };
}

function parseRetryAfter(value) {
  if (!value) return null;
  if (/^\d+$/.test(value)) return Number(value) * 1000;
  const t = Date.parse(value);
  return Number.isFinite(t) ? Math.max(0, t - Date.now()) : null;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(method, params) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
  });

  const budget = readBudget(res.headers);
  console.log('status', res.status, 'budget', budget);

  if (res.status === 429) {
    const wait = parseRetryAfter(res.headers.get('retry-after')) ?? 1000;
    console.log('429 received, waiting', wait, 'ms');
    await sleep(wait);
    return null;
  }

  // pace the next call if budget is low
  if (budget.remaining !== null && budget.resetAt) {
    const msLeft = Math.max(0, budget.resetAt - Date.now());
    if (budget.remaining <= 1 && msLeft > 0) {
      console.log('low budget, waiting', msLeft, 'ms');
      await sleep(msLeft);
    }
  }

  return res.json();
}

(async () => {
  for (let i = 0; i < 10; i++) {
    await call('eth_blockNumber', []);
  }
})();

用受控突发测量端点的真实上限

由于响应头的存在性和限制因提供商而异，唯一可靠的上限是你自己测量的。发送受控突发，记录每个响应上的响应头值，并记下第一个 429 出现的请求索引。在一天中的不同时间重复，以查看限制是共享的还是专用的。

用你自己的结果填写下表。不要将任何单次运行视为定论；重点是推导出你可以据此调整节奏的可持续速率，而不是发布基准。

• 结果表列：请求编号、状态、RateLimit-Remaining、RateLimit-Reset（原始）、Reset（归一化）、Retry-After、耗时毫秒。
• 第 1–N 行：记录直到第一个 429，然后停止并记下索引。
• 在不同时段重复突发 3 次；比较第一个 429 的索引。
• 推导可持续速率 = 第一个 429 前的成功请求数 / 经过秒数。
• 如果响应头缺失，也要记录——这会改变你的回退策略。

批处理、WebSocket 订阅与连接限制

JSON-RPC 批处理可以减少往返，但不一定减少预算消耗：许多提供商将批处理中的每个调用都计入限制，因此 50 个调用的批处理仍然消耗 50 个单位。批处理后读取响应头以确认它是如何计数的。

WebSocket 订阅则不同。订阅不会按消息消耗请求预算，但并发连接数可能单独受限。如果你打开许多订阅，可能会触及连接上限而不是请求上限，而且该上限可能不会反映在 RateLimit-Remaining 中。

有关端点选择和连接指导，请参阅 RPC 端点指南。有关网络特定背景，请参阅 以太坊 RPC 速率限制与 429 和 以太坊网络页面。

• 批处理通常按调用计数，而不是按 HTTP 请求计数。
• 订阅不消耗请求预算，但可能触及单独的连接上限。
• 批处理后检查响应头，以了解你的提供商如何计数。

响应头驱动节奏控制的局限与权衡

响应头驱动的节奏控制并非没有代价。它增加了少量客户端复杂性，而且只有在提供商实际发送响应头时才有效。有些提供商只在 429 响应中发送它们，有些在 CDN 或代理处剥离它们，还有些使用完全不同的名称。

节奏控制还以吞吐量换取稳定性。如果你放慢速度以保持在预算内，完成一批任务的时间可能比突发并重试的客户端更晚。对于延迟关键的工作负载，正确的答案可能是更高层级的套餐或专用端点，而不是更严格的节奏控制。

最后，响应头描述的是服务器对你预算的看法，而该预算可能与同一密钥或 IP 上的其他流量共享。客户端无法看到这种共享，因此应将 Remaining 视为上限，而不是保证。

• 需要提供商支持；响应头的存在性因提供商而异。
• 以吞吐量换取稳定性；对延迟关键的工作并不总是正确选择。
• 共享密钥或 IP 意味着 Remaining 是上限，而不是保证。

排查：我从未看到速率限制响应头

如果响应头缺失，请按顺序排查可能的原因。首先，检查它们是否只在 429 响应中出现——有些提供商只在你被限流时才发送预算响应头。其次，检查是否有 CDN 或反向代理剥离了它们；尤其是缓存响应可能不携带速率限制字段。

第三，检查响应头名称。有些提供商使用供应商前缀或不同的大小写约定。记录一次所有响应头并检查它们，而不是假定某个名称。第四，确认你读取的是响应头而不是 JSON-RPC 正文，正文从不包含速率限制字段。

如果这些都不适用，请回退到保守的固定节奏，并用上述突发方法测量你自己的上限。 OnFinality Learn 中心 有关于 429 处理和端点监控的相关指南。

• 响应头只在 429 上出现 → 将 429 Retry-After 作为你的主要信号。
• 被 CDN/代理剥离 → 直接针对源端点测试。
• 名称不同 → 记录一次所有响应头并检查。
• 读取的是正文而不是响应头 → 检查 res.headers，而不是 res.json()。
• 完全没有响应头 → 使用固定节奏并测量你自己的上限。

后续步骤：埋点、测量，然后调整节奏

首先记录一天中每个响应的响应头。你很快就能看出你的提供商是否发送它们、使用哪个家族，以及 Reset 如何表示。这单一改变将速率限制从谜团变为可测量的信号。

然后运行受控突发并填写结果表。使用你推导出的可持续速率配置令牌桶限速器，并将任何 429 Retry-After 视为权威。如果你需要的余量超过节奏控制所能提供的，请查看 RPC 定价 和 API 服务 选项，并考虑为繁重工作负载使用专用端点。

有关端点选择和故障转移的更广泛视角，请参阅 RPC 端点指南 和 RPC 节点监控与故障转移。

• 记录一天的响应头，以了解你的提供商的契约。
• 用受控突发和结果表测量你的上限。
• 根据可持续速率配置限速器；在 429 时遵循 Retry-After。