REST API 的速率限制

了解 REST API 速率限制、如何避免超过速率限制，以及如果超过了该怎么办。

在本文中

关于主要速率限制

          GitHub 限制可在特定时间内发出的 REST API 请求数。 此限制有助于防止滥用和拒绝服务攻击，并确保 API 仍可供所有用户使用。

某些终结点（如搜索终结点）的限制更严格。 有关这些终结点的详细信息，请参阅 速率限制的 REST API 终结点。 GraphQL API 还具有单独的主要速率限制。 请参阅“GraphQL API 的速率限制和查询限制”。

若要了解如何查看组织的 API 活动，包括哪些请求超出了主速率限制，请参阅 查看组织中的 API 洞察。

通常，可以根据身份验证方法计算 REST API 的主要速率限制，如下所示。

未认证用户的首要速率限制

如果仅提取公共数据，则可以发出未经身份验证的请求。 未经身份验证的请求与原始 IP 地址相关联，与发出请求的用户或应用程序无关。

未经身份验证的请求的速率限制为每小时 60 次请求。

身份验证用户的基础速率限制

可以使用 personal access token 发出 API 请求。 也可以授权 GitHub App or OAuth app，之后则可以代表你发出 API 请求。

所有这些请求均计入 5,000 次请求/小时的个人速率限制。 由 GitHub Enterprise Cloud 组织所有的 GitHub App 代表你发出的 请求比每小时 15,000 次请求的速率限制要高。 同样，如果你是 GitHub Enterprise Cloud 组织的成员，则由该组织拥有或批准的 OAuth app 代表你发出的请求，其速率限制也更高，为每小时 15,000 次请求。 但是，高限制应用发出的请求会减少可用于较低限制身份验证方法的剩余预算。 例如，如果具有 15,000 个请求限制的应用代表你发出 10,000 个请求，则你将用尽 personal access tokens 的 5,000 个请求预算，即使该应用还剩 5,000 个请求。

注意

          [企业审核日志 API 终结点](/rest/enterprise-admin/audit-log#get-the-audit-log-for-an-enterprise)存在速率限制：每个用户和 IP 地址每小时限 1,750 个查询。 如果集成收到速率限制错误（通常是 403 或 429 响应），则它应在向 GitHub API 发出另一个请求之前等待。

Git LFS 主要访问速率限制

上传或下载 Git LFS 内容时，需要 API 请求。 这些请求计入一个单独的速率限制桶，其中未经身份验证的请求的限制为每分钟 300 次，已经过身份验证的请求的限制为每分钟 3,000 次。

Git LFS 使用批处理 API，默认每个 API 请求可处理 100 个 Git LFS 对象。 这意味着未经身份验证的用户每分钟最多可下载 30,000 个 Git LFS 对象，而已经过身份验证的用户每分钟最多可上传/下载 300,000 个 Git LFS 对象。

主要速率限制适用于GitHub App安装

使用安装访问令牌进行身份验证的 GitHub Apps 使用安装的最低速率限制（每小时 5,000 个请求）。 如果安装位于 GitHub Enterprise Cloud 组织或企业上，则该安装的速率限制为每小时 15,000 个请求。

对于不在 GitHub Enterprise Cloud 组织或企业上的安装，安装的速率限制将根据用户和仓库数量进行缩放。 具有 20 个以上仓库的安装每小时会为每个仓库再接收 50 个请求。 位于拥有超过 20 个用户的组织的安装，每个用户每小时多获得 50 个请求。 速率限制增加的上限为每小时 12,500 个请求。

GitHub App 用户访问令牌（与安装访问令牌相反）的主要速率限制由经过身份验证的用户的主要速率限制决定。 此速率限制等于另一个 GitHub App 或 OAuth app 代表用户发出的任何请求数，加上用户通过 personal access token 发出的任何请求数。 有关详细信息，请参阅“REST API 的速率限制”。

主要速率限制 OAuth apps

OAuth 访问令牌的主要 OAuth app 速率限制由经过身份验证的用户的主要速率限制决定。 另一个 GitHub App 或 OAuth app 代表该用户发出的任何请求，以及用户使用 personal access token 发出的任何请求，都会与此速率限制共同计算。 请参阅经过身份验证的用户的主要速率限制。

OAuth 应用还可以使用其客户端 ID 和客户端密码来提取公共数据。 例如：

curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET -I https://api.github.com/meta

这些请求的速率限制为每 OAuth app 5,000 个请求。 如果应用由 GitHub Enterprise Cloud 组织所有，则速率限制为每小时 15,000 次请求。

注意

切勿在客户端代码或用户设备上运行的代码中包含应用的客户端密码。 客户端密码可用于为已授权应用的用户生成 OAuth 访问令牌，因此应始终保管好。

主要速率限制GITHUB_TOKEN在GitHub Actions中

可以在 GitHub Actions 工作流中使用内置 GITHUB_TOKEN 来验证请求。 请参阅“在工作流中使用 GITHUB_TOKEN 进行身份验证”。

GITHUB_TOKEN 的速率限制为每个存储库每小时 1,000 个请求。对属于 GitHub Enterprise Cloud 帐户的资源的请求的限制为每个存储库每小时 15,000 个请求。

关于二级速率限制

除了主要速率限制以外，GitHub 还强制执行次要速率限制以阻止滥用，让 API 可供所有用户所使用。

可能会在以下情况中遇到二级速率限制：

  • 发出的并发请求过多。 并发请求数量不能超过 100 个。 REST API 和 GraphQL API 都应用此限制。
  • 每分钟向单个终结点发出的请求数过多。 REST API 终结点每分钟允许发出的请求数不超过 900 点，GraphQL API 终结点每分钟允许发出的请求数不过超 2,000 点。 有关计分的详细信息，请参阅“计算次要速率限制的点数”。
  • 每分钟发出的请求数过多。 实时每 60 秒允许的 CPU 时间不超过 90 秒。 此 CPU 时间最多可以用于 GraphQL API 的时间不能超过 60 秒。 可以通过衡量 API 请求的总响应时间来大致估算出 CPU 时间。
  • 发出过多的请求，它们在短时间内会消耗过多的计算资源。
  • 短时间内在 GitHub 上创建的内容过多。 一般情况下，每分钟不超过 80 个内容生成请求，允许每小时不超过 500 个内容生成请求。 某些终结点的内容创建限制较低。 内容创建限制包括在 GitHub 的 Web 界面以及通过 REST API 和 GraphQL API 进行的操作。
  • 在短时间内发出过多的 OAuth 访问令牌请求。 每小时对于 GitHub Apps 和 OAuth apps 的 OAuth 访问令牌请求不允许超过 2,000 次。

上述次要速率限制可能随时更改，恕不另行通知。 您可能会因为某些未公开的原因而遇到次级速率限制。

计算次要速率限制的点数

某些次要速率限制由请求的点值确定。 对于 GraphQL 请求，这些点值与主要速率限制的点值分开来进行计算。

请求积分
不具有突变的 GraphQL 请求1
具有突变的 GraphQL 请求5
大多数 REST API GET、HEAD 和 OPTIONS 请求1
大多数 REST API POST、PATCH、PUT 或 DELETE 请求5

某些 REST API 终结点具有不公开共享的不同点成本。

检查你的速率限制状态

可以使用随每个响应一起发送的标头来确定主要速率限制的当前状态。

标头名称说明
x-ratelimit-limit每小时可以发出的最大请求数
x-ratelimit-remaining当前速率限制窗口中剩余的请求数
x-ratelimit-used当前速率限制窗口中你已发出的请求数
x-ratelimit-reset当前速率限制窗口重置的时间，单位为 UTC 纪元秒
x-ratelimit-resource请求计数的速率限制资源。 有关不同资源的详细信息，请参阅 速率限制的 REST API 终结点。

还可以调用 GET /rate_limit 终结点来检查速率限制。 调用此终结点不会计入主要速率限制，但会计入二级速率限制。 请参阅“速率限制的 REST API 终结点”。 情况允许时应使用速率限制响应标头，而不是调用 API 来检查速率限制。

没有办法检查二级速率限制的状态。

超出速度限制

如果超过主要速率限制，将收到一个 403 或 429 响应，x-ratelimit-remaining 标头将为 0。 应在 x-ratelimit-reset 标头所指定的时间之后，再尝试发出请求。

如果超过次要速率限制，将收到一个 403 或 429 响应，并显示一条错误消息，表明超过了次要速率限制。 如果有 retry-after 响应头，则应先等待数秒，然后再尝试请求。 如果 x-ratelimit-remaining 标头为 0，请勿在 x-ratelimit-reset 标头指定的时间（UTC 纪元时间的秒）之前重试您的请求。 否则，请在重试之前等待至少一分钟。 如果您的请求因二级速率限制而持续失败，请在每次重试之间等待呈指数级增长的时间，并在达到特定重试次数后抛出一个错误。

如果在受到速率限制的情况下继续发出请求，可能会导致禁止集成。

保持在速率限制范围内

应遵循最佳做法，帮助你保持在速率限制范围内。 请参阅“使用 REST API 的最佳做法”。

还可以流式传输审核日志来查看 API 请求。 这有助于排查超出速率限制的集成问题。 请参阅“流式处理企业审核日志”。

获取更高的速率限制

如果想要提高主要速率限制，请考虑发出经过身份验证的请求，而不是未经身份验证的请求。 经身份验证的请求的速率上限显著高于未经身份验证的请求。

在组织中使用personal access token进行自动化时，请考虑是否可以改用GitHub App。 使用安装访问令牌时，速率限制 GitHub Apps 会随着存储库数量和组织用户数量的增加而调整。 GitHub Apps 使用的 GitHub Enterprise Cloud 帐户速率限制高于 personal access tokens。 请参阅“关于创建GitHub应用”。