# REST API のトラブルシューティング

REST API の一般的な問題を診断して解決方法について説明します。

## レート制限エラー

GitHub では、すべてのユーザーが API を使用できるようにレート制限を適用します。 詳しくは、「[REST API のレート制限](/ja/rest/overview/rate-limits-for-the-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` ヘッダーで指定された時刻 (UTC エポック秒数)が過ぎる まで要求を再試行しないでください。
  `x-ratelimit-reset` ヘッダーは UTC エポック秒単位です。
* それ以外の場合は、少なくとも 1 分間待ってから再試行します。 要求が二次レート制限により継続して失敗する場合は、再試行の間は指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーを発生させます。

レート制限中に要求を続けると、統合を禁止する可能性があります。

レート制限を超えないようにする方法の詳細については、「[REST API を使用するためのベスト プラクティス](/ja/rest/guides/best-practices-for-using-the-rest-api)」を参照してください。

##

```
          `404 Not Found` 既存のリソース用
```

プライベート リソースへのアクセス要求を実行し、要求が正しく認証されていない場合は、`404 Not Found` 応答を受け取ります。 GitHub は、プライベート リポジトリの存在を確認しないように `404 Not Found` 応答ではなく `403 Forbidden` 応答を使用します。

要求しているリソースが存在することがわかっているときに `404 Not Found` 応答を受け取った場合は、認証をチェックする必要があります。 次に例を示します。

* personal access token (classic) を使用している場合は、次のことを確認してください。
  * トークンには、エンドポイントを使用するために必要なスコープがあります。 詳細については、「[OAuth アプリのスコープ](/ja/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)」および「[個人用アクセス トークンを管理する](/ja/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)」を参照してください。
  * トークンの所有者には、エンドポイントを使用するために必要なアクセス許可があります。 たとえば、エンドポイントを組織の所有者のみが使用できる場合、影響を受ける組織の所有者であるユーザーのみがエンドポイントを使用できます。
  * トークンの有効期限が切れていないか、取り消されていません。 詳しくは、「[トークンの有効期限と取り消し](/ja/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)」をご覧ください。
* fine-grained personal access token を使用している場合は、次のことを確認してください。
  * トークンには、エンドポイントを使用するために必要なアクセス許可があります。 必要なアクセス許可の詳細については、エンドポイントのドキュメントを参照してください。
  * トークンに指定されたリソース所有者は、エンドポイントが影響を受けるリソースの所有者と一致します。 詳しくは、「[個人用アクセス トークンを管理する](/ja/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)」をご覧ください。
  * このトークンは、エンドポイントが影響を及ぼすすべてのプライベートリポジトリにアクセス権を持っています 詳しくは、「[個人用アクセス トークンを管理する](/ja/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)」をご覧ください。
  * トークンの所有者には、エンドポイントを使用するために必要なアクセス許可があります。 たとえば、エンドポイントを組織の所有者のみが使用できる場合、影響を受ける組織の所有者であるユーザーのみがエンドポイントを使用できます。
  * トークンの有効期限が切れていないか、取り消されていません。 詳しくは、「[トークンの有効期限と取り消し](/ja/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)」をご覧ください。
* インストール アクセス トークン GitHub App を使用している場合は、次のことを確認してください。
  * GitHub App には、エンドポイントを使用するために必要なアクセス許可があります。 必要なアクセス許可の詳細については、エンドポイントのドキュメントを参照してください。
  * エンドポイントは、GitHub App がインストールされているアカウントが所有するリソースにのみ影響します。
  * GitHub App は、エンドポイントが影響を及ぼすすべてのリポジトリにアクセス権を持っています。
  * トークンの有効期限が切れていないか、取り消されていません。 詳しくは、「[トークンの有効期限と取り消し](/ja/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)」をご覧ください。
* GitHub App ユーザー アクセス トークンを使用している場合は、次のことを確認してください。
  * GitHub App には、エンドポイントを使用するために必要なアクセス許可があります。 必要なアクセス許可の詳細については、エンドポイントのドキュメントを参照してください。
  * トークンを承認したユーザーには、エンドポイントを使用するために必要なアクセス許可があります。 たとえば、エンドポイントを組織の所有者のみが使用できる場合、影響を受ける組織の所有者であるユーザーのみがエンドポイントを使用できます。
  * GitHub App は、エンドポイントが影響を及ぼすすべてのリポジトリにアクセス権を持っています。
  * ユーザーは、エンドポイントが影響を及ぼすリポジトリにアクセス権を持っています。
  * ユーザーは、GitHub App に対する更新されたアクセス許可を承認しました。 詳しくは、「[GitHub アプリの更新されたアクセス許可の承認](/ja/apps/using-github-apps/approving-updated-permissions-for-a-github-app)」をご覧ください。
* OAuth app ユーザー アクセス トークンを使用している場合は、次のことを確認してください。
  * トークンには、エンドポイントを使用するために必要なスコープがあります。 詳しくは、「[OAuth アプリのスコープ](/ja/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)」をご覧ください。
  * トークンを承認したユーザーには、エンドポイントを使用するために必要なアクセス許可があります。 たとえば、エンドポイントを組織の所有者のみが使用できる場合、影響を受ける組織の所有者であるユーザーのみがエンドポイントを使用できます。
  * 組織が所有するリソースに影響を与えるエンドポイントを使用している場合、組織は OAuth アプリのアクセスをブロックしていません。 アプリの所有者はアプリがブロックされているかどうかを確認できませんが、アプリのユーザーにこれをチェックするよう指示できます。 詳しくは、GitHub Free ドキュメントの「[OAuth アプリのアクセス制限について](/ja/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions)。
  * トークンの有効期限が切れていないか、取り消されていません。 詳しくは、「[トークンの有効期限と取り消し](/ja/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)」をご覧ください。
* GitHub Actions ワークフローで使用 `GITHUB_TOKEN` している場合は、次のことを確認する必要があります。
  * エンドポイントは、ワークフローが実行されているリポジトリが所有するリソースにのみ影響します。 組織が所有するリソースや別のリポジトリが所有するリソースなど、そのリポジトリの外部にあるリソースにアクセスする必要がある場合は、personal access token または GitHub App のアクセス トークンを使用する必要があります。

認証について詳しくは、「[REST API に対する認証](/ja/rest/overview/authenticating-to-the-rest-api)」をご覧ください。

URL の入力ミスについてもチェックする必要があります。 たとえば、末尾のスラッシュをエンドポイントに追加すると、`404 Not Found` になります。 エンドポイントのリファレンス ドキュメントを参照して、正しい URL であることを確認ください。

さらに、パス パラメーターは URL でエンコードする必要があります。 たとえば、パラメーター値に含まれるスラッシュは、`%2F` に置き換える必要があります。 パラメーター名にスラッシュを正しくエンコードしないと、エンドポイント URL が誤って解釈されます。

## 結果が見つかりません

リソースの一覧を返すほとんどのエンドポイントでは、改ページ調整をサポートしています。 これらのエンドポイントのほとんどでは、既定では最初の 30 個のリソースのみが返されます。 すべてのリソースを表示するには、結果を改ページ処理する必要があります。 詳しくは、「[REST API でのページネーションの使用](/ja/rest/guides/using-pagination-in-the-rest-api)」をご覧ください。

改ページ位置を正しく使用していて、予期した結果がすべて表示されない場合は、使用した認証資格情報が、必要なすべてのリソースにアクセスできるかどうかを確認してください。 たとえば、GitHub App インストール アクセス トークンを使用している場合、インストールに組織内のリポジトリのサブセットへのアクセスのみが許可されている場合、その組織内のすべてのリポジトリに対するすべての要求は、アプリのインストールでアクセスできるリポジトリのみを返します。

## 基本認証を使用する場合は認証が必要です

ユーザー名とパスワードによる基本認証はサポートされていません。 代わりに、personal access token または GitHub App または OAuth app のアクセストークンを使用する必要があります。 詳しくは、「[REST API に対する認証](/ja/rest/overview/authenticating-to-the-rest-api)」をご覧ください。

## タイムアウト

GitHub による API 要求の処理時間が 10 秒を超えると、その要求は GitHub によって終了され、タイムアウトの応答と "Server Error" メッセージが返されます。

GitHub は、API の速度と信頼性を保護するためにタイムアウト ウィンドウを変更する権利を留保しています。

```
          [githubstatus.com](https://www.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 で、pull request アクセス許可の書き込み権限と、コンテンツ アクセス許可の読み取り権限が必要であることを示しています。
* `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` は、GitHub App または fine-grained personal access token に、pull request アクセス許可の読み取り権限とコンテンツのアクセス許可の読み取り権限、または issue のアクセス許可の読み取り権限とコンテンツのアクセス許可の読み取り権限が必要であることを意味します。

## JSON の解析に関する問題

要求本文で無効な JSON を送信すると、`400 Bad Request` 応答と 「JSON の解析に関する問題」 というエラー メッセージが表示されることがあります。 リンターまたは JSON バリデーターを使用して、JSON 内のエラーを特定できます。

## 本文は JSON オブジェクトである必要がある

エンドポイントで JSON オブジェクトが必要であり、要求本文を JSON オブジェクトとして書式設定しなかった場合は、`400 Bad Request` 応答と 「本文は JSON オブジェクトであること」 というエラー メッセージが表示されることがあります。

## 無効な要求

必要なパラメーターを省略した場合、またはパラメーターに間違った型を使用すると、`422 Unprocessable Entity` 応答と "無効な要求" エラー メッセージが表示されることがあります。 たとえば、パラメーター値を配列として指定しても、エンドポイントで文字列が必要な場合、このエラーが発生します。 エンドポイントのリファレンス ドキュメントを参照して、正しいパラメーター型を使用していること、および必要なすべてのパラメーターが含まれているかどうかを確認できます。

## 検証に失敗しました

要求を処理できなかった場合は、`422 Unprocessable Entity` 応答と 「検証に失敗しました」 というエラー メッセージが表示されることがあります。 応答本文には、問題の診断に役立つ `errors` プロパティを含む `code` プロパティが含まれます。

| Code             | 説明                                                                  |
| ---------------- | ------------------------------------------------------------------- |
| `missing`        | リソースが存在しません。                                                        |
| `missing_field`  | 必要なパラメーターが指定されませんでした。 エンドポイントのドキュメントを確認して、必要なパラメーターを確認します。          |
| `invalid`        | パラメータのフォーマットが無効です。 詳細については、エンドポイントのドキュメントを参照してください。                 |
| `already_exists` | 別のリソースの値は、パラメーターの 1 つと同じです。 これは、一意のキー（ラベル名など）が必要なリソースで発生する可能性があります。 |
| `unprocessable`  | 指定されたパラメーターが無効でした。                                                  |
| `custom`         | エラーを診断するには、`message` プロパティを参照してください。                                |

## サポートされている SDK バージョンではありません

API バージョンを指定するには、`X-GitHub-Api-Version` ヘッダーを使用する必要があります。 次に例を示します。

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

存在しないバージョンを指定すると、サポートされていないバージョンに関する `400 Bad Request` エラーとメッセージが表示されます。

詳しくは、「[API のバージョン](/ja/rest/overview/api-versions)」をご覧ください。

## ユーザーエージェントが必要です

```
          `User-Agent` ヘッダーのない要求は拒否されます。 
          `User-Agent` 値には、ユーザー名またはアプリケーションの名前を使用してください。
```

curl は、既定で有効な `User-Agent` ヘッダーを送信します。

## その他のエラー

ここで対処されていないエラーが発生した場合は、API が提供するエラー メッセージを参照してください。 ほとんどのエラー メッセージは、何が間違っているかについての手掛かりと、関連するドキュメントへのリンクを提供します。

予期しないエラーが発生した場合は、[githubstatus.com](https://www.githubstatus.com/) または [GitHub 状態 API](https://www.githubstatus.com/api) を使用して、API に影響するインシデントをチェックできます。

## 参考資料

* [REST API を使用するためのベスト プラクティス](/ja/rest/guides/best-practices-for-using-the-rest-api)
* [Webhook のトラブルシューティング](/ja/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks)
* [GitHub アプリを作成するためのベスト プラクティス](/ja/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)