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 ヘッダーで指定された時刻 (UTC エポック秒数)が過ぎるまで要求を再試行しないでください。 x-ratelimit-reset ヘッダーは UTC エポック秒単位です。
それ以外の場合は、少なくとも 1 分間待ってから再試行します。セカンダリレート制限の要求が継続して失敗する場合は、再試行の間に指数関数的に増加する時間を待ち、特定の回数の再試行の後にエラーをスローします。

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

レート制限を超えないようにする方法の詳細については、「REST API を使用するためのベストプラクティス」を参照してください。

`404 Not Found` 既存のリソースをエクスポートする

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

要求しているリソースが存在することがわかっているときに 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 に対する認証」を参照してください。

Timeouts

GitHub がAPIを処理するのに 10 秒以上かかると、GitHub はリクエストを終了させ、タイムアウトのレスポンスとサーバーエラーメッセージが返されます。

GitHub は、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 が pull request アクセス許可への書き込みアクセス権とコンテンツアクセス許可への読み取りアクセス権を必要とすることを意味します。
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read は、GitHub App または fine-grained personal access token には、pull request アクセス許可への読み取りアクセス権とコンテンツアクセス許可への読み取りアクセス権、またはイシューのアクセス許可への読み取りアクセス許可とコンテンツアクセス許可への読み取りアクセスが必要という意味です。

JSON の解析に関する問題

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

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

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

無効な要求

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

Validation Failed

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

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

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

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

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

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

詳しくは、「API のバージョン」を参照してください。