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 App 用户访问令牌，则应确保
    • 该令牌具有使用该端点所需的范围。有关更多信息，请参阅“OAuth 应用的范围”。
    • 授权令牌的用户拥有使用端点所需的任何权限。例如，如果端点只能由组织所有者使用，则只有受影响组织的所有者才能使用该端点。
    • 如果使用的是会影响组织拥有的资源的端点，则组织不会阻止 OAuth 应用访问。应用所有者无法查看其应用是否被阻止，但他们可以指示应用用户检查此问题。有关更多信息，请参阅“关于 OAuth 应用访问限制”。
    • 令牌尚未过期或被撤销。有关更多信息，请参阅“令牌过期和撤销”。
  • 如果您在 GitHub Actions 工作流程中使用 GITHUB_TOKEN，则应确保
    • 该端点仅影响运行工作流程的存储库拥有的资源。如果您需要访问该存储库之外的资源，例如组织拥有的资源或其他存储库拥有的资源，则应使用个人访问令牌或 GitHub 应用的访问令牌。

有关身份验证的更多信息，请参阅“对 REST API 进行身份验证”。

您还应检查 URL 中是否有错别字。例如，在端点末尾添加斜杠会导致 404 Not Found。您可以参考端点的参考文档以确认您拥有正确的 URL。

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

缺少结果

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

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

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

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

超时

如果 GitHub 处理 API 请求的时间超过 10 秒，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 应用或细粒度个人访问令牌需要对内容权限进行读取访问。
  • X-Accepted-GitHub-Permissions: pull_requests=write,contents=read 表示您的 GitHub 应用或细粒度个人访问令牌需要对拉取请求权限进行写入访问，以及对内容权限进行读取访问。
  • X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read 表示您的 GitHub 应用或细粒度个人访问令牌需要对拉取请求权限进行读取访问以及对内容权限进行读取访问，或者对问题权限进行读取访问以及对内容权限进行读取访问。

解析 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缺少必需的参数。请查看端点文档以了解所需参数。
无效参数格式无效。请查看端点文档以获取更详细的信息。
已存在另一个资源与您的参数之一具有相同的值。这可能发生在必须具有唯一键（例如标签名称）的资源中。
无法处理提供的参数无效。
自定义请参考 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 的事件。

进一步阅读