排查 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 epoch 秒表示。
  • 否则请至少等待一分钟后再重试。如果仍因二级速率限制而失败，请在重试之间采用指数递增的等待时间，并在达到一定重试次数后抛出错误。

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

有关避免触发速率限制的更多信息，请参阅 使用 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 处理 API 请求的时间超过 10 秒，GitHub 将终止该请求，并返回超时响应以及 “Server Error” 信息。

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

你可以在 githubstatus.com 查看 REST API 状态，以判断超时是否源于 API 本身的问题。也可以尝试简化请求或稍后重试，例如将每页请求的项目数从 100 减少到更少。

资源不可访问

如果使用 GitHub App 或细粒度个人访问令牌时收到 “Resource not accessible by integration” 或 “Resource not accessible by personal access token” 错误，则说明你的令牌权限不足。有关所需权限的详细信息，请查看对应端点的文档。

你可以使用 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_requests 权限的写入权限以及对 contents 权限的读取权限。
  • X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read 表示你的 GitHub App 或细粒度个人访问令牌可以选择（1）对 pull_requests 权限的读取以及对 contents 权限的读取；或（2）对 issues 权限的读取以及对 contents 权限的读取。

JSON 解析问题

如果在请求体中发送了无效的 JSON，可能会收到 400 Bad Request 响应和 “Problems parsing JSON” 错误信息。可使用 linter 或 JSON 验证工具帮助定位 JSON 错误。

请求体应为 JSON 对象

如果端点期望收到 JSON 对象而你的请求体未按 JSON 对象格式组织，可能会收到 400 Bad Request 响应和 “Body should be a JSON object” 错误信息。

无效请求

如果遗漏了必需的参数或对参数使用了错误的类型，可能会收到 422 Unprocessable Entity 响应和 “Invalid request” 错误信息。例如，当端点期望字符串而你提供了数组时就会出现此错误。请参考端点的参考文档，确认参数类型正确且已包含所有必需参数。

验证失败

如果你的请求无法被处理，可能会收到 422 Unprocessable Entity 响应和 “Validation Failed” 错误信息。响应体中会包含一个 errors 属性，其中的 code 可帮助诊断具体问题。

代码描述
missing资源不存在。
missing_field缺少必需的参数。请查看端点文档了解哪些参数是必填的。
invalid参数的格式无效。请参考端点文档获取更具体的信息。
already_exists已有其他资源使用了与你提供的参数相同的值。此情况常见于需要唯一键的资源（例如标签名称）。
unprocessable提供的参数无效。
custom请参考 message 属性以诊断错误。

版本不受支持

应使用 X-GitHub-Api-Version 头部指定 API 版本，例如：

curl --header "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen

如果指定了不存在的版本，将返回 400 Bad Request 错误并提示该版本不受支持。

更多信息请参阅 API 版本。

需要 User-Agent

未包含有效 User-Agent 头部的请求将被拒绝。User-Agent 的值应使用你的用户名或应用名称。

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

其他错误

如果遇到本文未覆盖的错误，请参考 API 返回的错误信息。大多数错误信息会提供问题线索并附带相关文档链接。

如果出现意外故障，可使用 githubstatus.com 或 GitHub 状态 API 检查是否有影响 API 的事件。

延伸阅读

© . This site is unofficial and not affiliated with GitHub, Inc.