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 纪元秒为单位。
  • 否则，请在重试之前等待至少一分钟。 如果请求由于次要速率限制而继续失败，请等待呈指数级增加的重试间隔秒数，当达到特定的重试次数之后，将会抛出错误。

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

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

有关如何避免超过速率限制的详细信息，请参阅 使用 REST API 的最佳做法。

适用于现有资源的 404 Not Found

如果请求访问一个专用的资源，但未正确对此请求进行身份验证，将会收到一个 404 Not Found 响应。 GitHub 使用一个 404 Not Found 响应而不是 403 Forbidden 响应，以避免确认是否存在专用存储库。

如果知道所请求的资源存在但收到了一个 404 Not Found 响应，则应检查身份验证。 例如：

  • 如果正在使用 personal access token (classic)，应当确保：
    • 令牌具有使用端点所需的权限范围。 有关详细信息，请参阅 OAuth 应用的范围 和 管理个人访问令牌。
    • 令牌的所有者拥有使用端点所需的任何权限。 例如，如果一个端点只能由组织所有者使用，则只有身为受影响组织的所有者的用户能够使用此端点。
    • 令牌尚未过期或被撤销。 有关详细信息，请参阅“令牌过期和吊销”。
  • 如果正在使用 fine-grained personal access token，应当确保：
    • 令牌拥有使用端点所需的权限。 有关所需权限的详细信息，请参阅端点的文档。
    • 为令牌指定的资源所有者与端点将会影响的资源的所有者匹配。 有关详细信息，请参阅“管理个人访问令牌”。
    • 令牌有权访问端点将会影响的任何专用存储库。 有关详细信息，请参阅“管理个人访问令牌”。
    • 令牌的所有者拥有使用端点所需的任何权限。 例如，如果一个端点只能由组织所有者使用，则只有身为受影响组织的所有者的用户能够使用此端点。
    • 令牌尚未过期或被撤销。 有关详细信息，请参阅“令牌过期和吊销”。
  • 如果正在使用 GitHub App 安装访问令牌，应当确保：
    • GitHub App 拥有使用端点所需的权限。 有关所需权限的详细信息，请参阅端点的文档。
    • 端点只影响安装了 GitHub App 的帐户所拥有的资源。
    • GitHub App 有权访问端点将会影响的任何存储库。
    • 令牌尚未过期或被撤销。 有关详细信息，请参阅“令牌过期和吊销”。
  • 如果正在使用 GitHub App 用户访问令牌，应当确保：
    • GitHub App 拥有使用端点所需的权限。 有关所需权限的详细信息，请参阅端点的文档。
    • 授权令牌的用户拥有使用端点所需的任何权限。 例如，如果一个端点只能由组织所有者使用，则只有身为受影响组织的所有者的用户能够使用此端点。
    • GitHub App 有权访问端点将会影响的任何存储库。
    • 用户有权访问端点将会影响的任何存储库。
    • 用户已批准对 GitHub App 的任何更新后的权限。 有关详细信息，请参阅“批准 GitHub 应用的更新权限”。
  • 如果正在使用 OAuth app 用户访问令牌，应当确保：
    • 令牌具有使用端点所需的权限范围。 有关详细信息，请参阅“OAuth 应用的范围”。
    • 授权令牌的用户拥有使用端点所需的任何权限。 例如，如果一个端点只能由组织所有者使用，则只有身为受影响组织的所有者的用户能够使用此端点。
    • 如果正在使用一个将会影响组织拥有的资源的端点，则表明组织未阻止访问 OAuth 应用程序。 应用程序所有者无法查看他们的应用程序是否被阻止，但可以指示应用程序用户执行这一检查。 有关详细信息，请参阅 关于 OAuth 应用访问限制。
    • 令牌尚未过期或被撤销。 有关详细信息，请参阅“令牌过期和吊销”。
  • 如果正在一个 GitHub Actions 工作流中使用 GITHUB_TOKEN，应当确保：
    • 端点只影响运行工作流的存储库所拥有的资源。 如果需要访问此存储库外部的资源（例如组织拥有的资源或者另一个存储库拥有的资源），应当使用一个 personal access token 或者一个适用于 GitHub App 的访问令牌。

有关身份验证的详细信息，请参阅 对 REST API 进行身份验证。

还应在 URL 中检查拼写错误。 例如，为端点添加一个尾部反斜杠将会导致一个 404 Not Found。 可以参考端点的参考文档，以确认 URL 正确。

此外，所有路径参数均须经过 URL 编码。 例如，必须将参数值中的任意斜线替换为 %2F。 如果未正确对参数名称中的斜线进行编码，就会造成端点 URL 解析错误。

缺少结果

大多数将会返回资源列表的端点都支持分页。 对于大多数这样的端点，默认只返回前 30 个资源。 要查看所有资源，需要对结果进行分页显示。 有关详细信息，请参阅“在 REST API 中使用分页”。

如果正确使用了分页功能，但仍看不到预期的所有结果，则应确认所使用的身份验证凭据有权访问所有的预期资源。 例如，如果正在使用 GitHub App 安装访问令牌，并且只授权此安装访问组织中的一部分存储库，则向此组织中的所有存储库发出的任何请求将只返回所安装的应用程序能够访问的那些存储库。

使用基本身份验证时，需要进行身份验证

不支持通过用户名和密码进行身份验证。 相反，应当使用一个 personal access token 或者一个适用于 GitHub App 或 OAuth app 的访问令牌。 有关详细信息，请参阅“对 REST API 进行身份验证”。

超时

如果 GitHub Enterprise Cloud 花费 10 秒以上的时间处理一个 API 请求，GitHub Enterprise Cloud 将会终止此请求，你将收到一个超时响应和一条“服务器错误”消息。

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

可以在 githubstatus.com 上检查 REST API 的状态，以确定超时是否是由于 API 出现问题而造成的。 也可以尝试简化请求，或者稍后尝试发出请求。 例如，如果正在请求一个页面上的 100 个项，可以尝试减少所请求的项数量。

无法访问资源

如果正在使用 GitHub App 或 fine-grained personal access token，并且收到“无法通过集成访问资源”或“personal access token 无法访问资源”错误，则表明令牌的权限不足。 有关所需权限的详细信息，请参阅端点的文档。

可以使用 X-Accepted-GitHub-Permissions 标头确定访问 REST API 端点所需的权限。

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

例如：

  • X-Accepted-GitHub-Permissions: contents=read 表示 GitHub App 或 fine-grained personal access token 需要对内容权限的读取访问权限。
  • X-Accepted-GitHub-Permissions: pull_requests=write,contents=read 表示 GitHub App 或 fine-grained personal access token 需要对拉取请求权限的写入访问权限和对内容权限的读取访问权限。
  • X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read 表示 GitHub App 或 fine-grained personal access token 需要对拉取请求权限的读取访问权限和对内容权限的读取访问权限，或对问题权限的读取访问权限和对内容权限的读取访问权限。

分析 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 --标头 "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 的事件。

其他阅读材料