REST API 故障排除

了解如何诊断和解决 REST API 的常见问题。

本文内容

速率限制错误

GitHub 实施速率限制以确保 API 可供所有用户使用。更多信息，请参见 "REST API 的速率限制"。

如果超过主要速率限制，您将收到 `403 Forbidden` 或 `429 Too Many Requests` 响应，并且 `x-ratelimit-remaining` 头将为 `0`。如果超过辅助速率限制，您将收到 `403 Forbidden` 或 `429 Too Many Requests` 响应以及指示您超过辅助速率限制的错误消息。

如果收到速率限制错误，则应根据以下指南暂时停止发出请求

  • 如果存在 `retry-after` 响应头，则应在经过指定秒数后才能重试请求。
  • 如果 `x-ratelimit-remaining` 头为 `0`，则应在 `x-ratelimit-reset` 头指定的时间后才能发出另一个请求。`x-ratelimit-reset` 头以 UTC 时间戳秒为单位。
  • 否则，请至少等待一分钟后再重试。如果您的请求由于辅助速率限制而继续失败，请在重试之间等待呈指数增长的时长，并在特定次数的重试后抛出错误。

在您受到速率限制时继续发出请求可能会导致您的集成被禁止。

有关如何避免超过速率限制的更多信息，请参见 "REST API 的最佳实践"。

404 Not Found 资源不存在

如果您发出请求以访问私有资源并且您的请求未正确进行身份验证，您将收到 `404 Not Found` 响应。GitHub 使用 `404 Not Found` 响应而不是 `403 Forbidden` 响应，以避免确认私有代码库的存在。

如果您在知道您请求的资源存在时收到 `404 Not Found` 响应，则应检查您的身份验证。例如：

  • 如果您使用的是个人访问令牌（经典），则应确保：
    • 令牌具有使用端点所需的范围。更多信息，请参见 "OAuth 应用的范围" 和 "管理您的个人访问令牌"。
    • 令牌的所有者具有使用端点所需的任何权限。例如，如果端点只能由组织所有者使用，则只有受影响组织的所有者才能使用该端点。
    • 令牌尚未过期或被吊销。更多信息，请参见 "令牌过期和吊销"。
  • 如果您使用的是细粒度个人访问令牌，则应确保：
    • 令牌具有使用端点所需的权限。有关所需权限的更多信息，请参阅端点的文档。
    • 为令牌指定的资源所有者与端点将影响的资源的所有者匹配。更多信息，请参见 "管理您的个人访问令牌"。
    • 令牌可以访问端点将影响的任何私有代码库。更多信息，请参见 "管理您的个人访问令牌"。
    • 令牌的所有者具有使用端点所需的任何权限。例如，如果端点只能由组织所有者使用，则只有受影响组织的所有者才能使用该端点。
    • 令牌尚未过期或被吊销。更多信息，请参见 "令牌过期和吊销"。
  • 如果您使用的是 GitHub App 安装访问令牌，则应确保：
    • GitHub App 具有使用端点所需的权限。有关所需权限的更多信息，请参阅端点的文档。
    • 端点仅影响安装了 GitHub App 的帐户拥有的资源。
    • GitHub App 可以访问端点将影响的任何代码库。
    • 令牌尚未过期或被吊销。更多信息，请参见 "令牌过期和吊销"。
  • 如果您使用的是 GitHub App 用户访问令牌，则应确保：
    • GitHub App 具有使用端点所需的权限。有关所需权限的更多信息，请参阅端点的文档。
    • 授权令牌的用户具有使用端点所需的任何权限。例如，如果端点只能由组织所有者使用，则只有受影响组织的所有者才能使用该端点。
    • GitHub App 可以访问端点将影响的任何代码库。
    • 用户可以访问端点将影响的任何代码库。
    • 用户已批准您的 GitHub App 的任何更新的权限。更多信息，请参见 "批准 GitHub App 的更新权限"。
  • 如果您使用的是 OAuth 应用用户访问令牌，则应确保：
    • 令牌具有使用端点所需的范围。更多信息，请参见 "OAuth 应用的范围"。
    • 授权令牌的用户具有使用端点所需的任何权限。例如，如果端点只能由组织所有者使用，则只有受影响组织的所有者才能使用该端点。
    • 如果您使用的是将影响组织拥有的资源的端点，则组织尚未阻止 OAuth 应用访问。应用所有者无法查看其应用是否被阻止，但他们可以指示应用用户检查此问题。更多信息，请参见 "关于 OAuth 应用访问限制"。
    • 令牌尚未过期或被吊销。更多信息，请参见 "令牌过期和吊销"。
  • 如果您在 GitHub Actions 工作流程中使用 `GITHUB_TOKEN`，则应确保：
    • 端点仅影响工作流程正在运行的代码库拥有的资源。如果您需要访问该代码库外部的资源，例如组织拥有的资源或其他代码库拥有的资源，则应使用个人访问令牌或 GitHub App 的访问令牌。

有关身份验证的更多信息，请参见 "REST API 的身份验证"。

您还应检查 URL 中的拼写错误。例如，在端点后面添加尾部斜杠将导致 `404 Not Found`。您可以参考端点的参考文档以确认您拥有正确的 URL。

此外，任何路径参数都必须进行 URL 编码。例如，参数值中的任何斜杠都必须替换为 `%2F`。如果您没有正确编码参数名称中的任何斜杠，则端点 URL 将被误解。

结果缺失

大多数返回资源列表的端点都支持分页。对于大多数这些端点，默认情况下仅返回前 30 个资源。为了查看所有资源，您需要遍历结果。更多信息，请参见 "REST API 中的使用分页"。

如果您正确使用分页但仍然没有看到您期望的所有结果，则应确认您使用的身份验证凭据可以访问所有期望的资源。例如，如果您使用的是 GitHub App 安装访问令牌，如果安装仅被授予对组织中一部分代码库的访问权限，则对该组织中所有代码库的任何请求都将仅返回该 App 安装可以访问的代码库。

使用基本身份验证时需要身份验证

不支持使用您的用户名和密码进行基本身份验证。相反，您应该使用个人访问令牌或 GitHub App 或 OAuth 应用的访问令牌。更多信息，请参见 "REST API 的身份验证"。

超时

如果 GitHub 需要超过 10 秒才能处理 API 请求，GitHub 将终止该请求，您将收到超时响应和“服务器错误”消息。

GitHub 保留更改超时窗口的权利，以保护 API 的速度和可靠性。

您可以访问githubstatus.com 检查 REST API 的状态，以确定超时是否由 API 问题引起。您也可以尝试简化您的请求或稍后再尝试您的请求。例如，如果您正在请求一页上的 100 个项目，您可以尝试请求更少的项目。

资源不可访问

如果您正在使用 GitHub App 或细粒度个人访问令牌，并且收到“集成无法访问资源”或“个人访问令牌无法访问资源”错误，则您的令牌权限不足。有关所需权限的更多信息，请参阅端点的文档。

您可以使用X-Accepted-GitHub-Permissions 头来识别访问 REST API 端点所需的权限。

X-Accepted-GitHub-Permissions 头的值是用逗号分隔的所需权限列表。有时，您可以从多个权限集中进行选择。在这些情况下，多个逗号分隔的列表将用分号分隔。

例如

  • X-Accepted-GitHub-Permissions: contents=read 表示您的 GitHub App 或细粒度个人访问令牌需要对 contents 权限进行读取访问。
  • X-Accepted-GitHub-Permissions: pull_requests=write,contents=read 表示您的 GitHub App 或细粒度个人访问令牌需要对 pull request 权限进行写入访问，并对 contents 权限进行读取访问。
  • X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read 表示您的 GitHub App 或细粒度个人访问令牌需要对 pull request 权限进行读取访问并对 contents 权限进行读取访问，或者需要对 issues 权限进行读取访问并对 contents 权限进行读取访问。

JSON 解析问题

如果您在请求正文中发送无效的 JSON，您可能会收到400 Bad Request响应和“JSON 解析问题”错误消息。您可以使用 linter 或 JSON 验证器来帮助您识别 JSON 中的错误。

正文应为 JSON 对象

如果端点期望一个 JSON 对象，而您没有将请求正文格式化为 JSON 对象，您可能会收到400 Bad Request响应和“正文应为 JSON 对象”错误消息。

无效请求

如果您省略了必需的参数或使用了错误的参数类型，您可能会收到422 Unprocessable Entity响应和“无效请求”错误消息。例如，如果您将参数值指定为数组，但端点期望的是字符串，则会收到此错误。您可以参考端点的参考文档，以验证您是否使用了正确的参数类型以及是否包含所有必需的参数。

验证失败

如果您的请求无法处理，您可能会收到422 Unprocessable Entity响应和“验证失败”错误消息。响应正文将包含一个errors属性，其中包含一个code属性，可以帮助您诊断问题。

代码描述
missing资源不存在。
missing_field未指定必需的参数。查看端点的文档以了解哪些参数是必需的。
invalid参数的格式无效。查看端点文档以获取更具体的信息。
already_exists另一个资源与您的一个参数具有相同的值。这可能发生在必须具有某些唯一键（例如标签名称）的资源中。
unprocessable提供的参数无效。
custom请参考message属性来诊断错误。

不支持的版本

您应该使用X-GitHub-Api-Version 头来指定 API 版本。例如

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

如果您指定了不存在的版本，您将收到400 Bad Request错误和关于不支持该版本的消息。

有关更多信息，请参阅“API 版本”。

需要用户代理

没有有效User-Agent头的请求将被拒绝。您应该使用您的用户名或应用程序的名称作为User-Agent值。

curl 默认发送有效的User-Agent头。

其他错误

如果您遇到此处未解决的错误，您应该参考 API 给您的错误消息。大多数错误消息都会提供有关错误原因的线索以及指向相关文档的链接。

如果您观察到意外故障，您可以使用githubstatus.com 或GitHub 状态 API 检查影响 API 的事件。

进一步阅读