基于账户的速率限制

默认情况下，GraphQL Analytics API 按用户或 API 令牌应用速率限制。随着你扩展——添加更多 zone 和账户——所有分析流量都会争夺这一单一的按凭据配额。

基于账户的速率限制 改为按账户和 zone 应用限制。每个账户和 zone 都有独立配额，因此单个用户或令牌可以同时查询许多资源，而不会耗尽一份共享配额。如果你跨多个 zone 或账户查询分析数据，这是推荐模型。

• 随占用规模扩展。 吞吐量随所查询的账户和 zone 数量增长，而不是受限于单一的按凭据上限。
• Enterprise 享有更高配额。 Enterprise 客户获得更高的默认按账户（15 rps）和按 zone（10 rps）配额。
• 易于提高限制。 需要更多余量？请与我们联系，我们可以按需提高限制。

向现有 GraphQL API 端点（https://api.cloudflare.com/client/v4/graphql）的请求发送以下 HTTP 标头：

X-Rate-Limit-Type: account-based

端点 URL 和凭据保持不变。不带此标头的请求继续使用默认的按用户 / 按令牌限制，因此你可以逐步采用。

单个 accounts 块计为对所引用账户的一次请求。单个 zones 块计为对所引用 zone 的一次请求；如果 zones 块嵌套在 accounts 块内，则改为计入该账户。

由于限制按资源应用，单个用户或令牌可用的总吞吐量会随你查询的不同账户和 zone 数量扩展。

大多数查询无需更改。只有在顶层（viewer）选择 列表 或 范围 的 zone 的查询需要调整：将这些 zone 嵌套到单个 accounts 块中。调整后的查询在两种 速率限制模型下都有效。

查询单个 zone——无需更改：

{
  viewer {
    zones(filter: { zoneTag: "<ZONE_TAG>" }) {
      # ...
    }
  }
}

查询单个账户——无需更改：

{
  viewer {
    accounts(filter: { accountTag: "<ACCOUNT_TAG>" }) {
      # ...
    }
  }
}

查询 zone 列表或范围——嵌套到所属账户中：

# Not supported: a list of zones at the viewer level
{
  viewer {
    zones(filter: { zoneTag_in: ["<ZONE_A>", "<ZONE_B>"] }) {
      # ...
    }
  }
}

# Supported: the same zones nested inside their account
{
  viewer {
    accounts(filter: { accountTag: "<ACCOUNT_TAG>" }) {
      zones(filter: { zoneTag_in: ["<ZONE_A>", "<ZONE_B>"] }) {
        # ...
      }
    }
  }
}

zoneTag_gt 等范围筛选器同样适用。查询语义相同——你只需要拥有这些 zone 的账户 tag，而你已经拥有该信息。

如果你需要超过默认的按账户或按 zone 吞吐量，请联系 Cloudflare 客户团队，为所查询的特定账户和 zone 申请提高限制。此模型下的提高按资源应用，并且会很快生效，无需工程发布。

超出限制时，API 会返回错误，将 extensions.code 设置为 budget，并指明被限流的账户或 zone：

{
  "data": null,
  "errors": [
    {
      "extensions": { "code": "budget", "timestamp": "2026-01-01T01:01:01Z" },
      "message": "Account <ACCOUNT_TAG> has exceeded its rate limit. Please try again after 5 minutes. Refer to this page for more details about rate limits: https://developers.cloudflare.com/analytics/graphql-api/limits/",
      "path": null
    }
  ]
}

对应的 zone 错误会报告 Zone <ZONE_TAG> has exceeded its rate limit。请在 5 分钟窗口后重试，将流量分散到多个资源，或申请更高限制。