GitHub REST APIの403や429が続くときは、権限を追加する前に、応答本文とrate-limit関連ヘッダーを確認します。403は権限エラーにもrate limitにも使われるため、状態だけで修正先を決めると、必要のない権限変更や再試行を増やしてしまいます。
この記事では、APIを使うCIや連携処理の担当者が、一次制限・二次制限・別の拒否を分け、再開時刻と要求量を調整する手順を扱います。tokenの発行・権限拡大・契約変更は行いません。
目次
失敗応答を機密を除いて残す
method、endpoint、時刻、HTTPステータス、本文のエラー種別、認証方式を記録します。Authorizationやtoken全文、署名付きURLを貼らず、どのjob・アプリの要求か追える識別子を使います。
表は横にスクロールできます
| 応答項目 | 確認する意味 |
|---|---|
| 本文のmessage | rate limitなのか、別の拒否なのか |
| x-ratelimit-remaining | 対象枠の残量 |
| x-ratelimit-reset | 枠のreset時刻を示すUTC epoch秒 |
| x-ratelimit-resource | どのresourceの枠か |
| retry-after | 指定された待機秒数 |
ヘッダーの欠落や、clientが本文を捨てている場合は、分かっていない項目を補って判断しません。安全に取得できる応答情報を残すよう、呼出し元のログ設計を確認します。
一次制限と二次制限を分ける
GitHubの公式資料は、一次制限を認証方式やresource等に応じた時間枠の要求量、二次制限を同時・短時間の要求等に対する追加の制限として説明しています。一次の残量があることだけでは、二次制限に達していない証明にはなりません。GitHub：Rate limits for the REST API（新しいタブで開く）
表は横にスクロールできます
| 観察 | 次の確認 |
|---|---|
| 403/429でremainingが0 | reset時刻と対象resource |
| 本文がsecondary rate limitを示す | retry-after、要求の集中、再試行量 |
| 403だが本文が権限・resource accessを示す | 認証・権限・対象repositoryの別診断 |
| 401や別のvalidation error | そのエラーの原因。rate limitと決めない |
同じtokenを使う複数jobや連携処理が、同じ枠や要求の集中に関係する場合があります。自分の一つのscriptだけを数えず、どの認証主体・resourceへ要求が集まるかを整理します。検索endpoint等の枠も、一般のREST APIと一律に扱いません。
待機条件を満たしてから再開する
一次制限でremainingが0なら、resetで示された時刻より前に再試行しません。resetは待機秒数そのものではなく時刻なので、現在のUTC時刻と単位を合わせて扱います。
二次制限では、retry-afterがあればその秒数を待ちます。remainingが0ならresetも確認し、それらの指定がない場合の扱いは公式資料に従います。現行資料は、その場合少なくとも一分待ち、失敗が続くときは待機を指数的に増やし、有限回でエラーとして終了するよう案内しています。
待機中に別workerが同じ要求を連打していれば、単一jobのsleepだけでは要求集中を抑えられません。client内部の再試行と、job・queue側の再試行が重なっていないかも確認します。
要求の出し方を小さく変える
回復確認では、まず並列度と不要なpollingを見直します。GitHubの公式ベストプラクティスは、二次制限を避けるための要求の直列化や、条件付きrequest、webhook等を利用した不要なpollingの削減を案内しています。endpointごとに利用できる方法を確認してください。GitHub：Best practices for using the REST API（新しいタブで開く）
表は横にスクロールできます
| 見直す箇所 | 観察する変化 |
|---|---|
| 同時に動くjob | 瞬間的な要求集中が減るか |
| 更新確認のpolling | 必要のない同一取得を減らせるか |
| ページング | 同じpageの再取得や取りこぼしがないか |
| 二重の再試行 | 一回の失敗が多数の要求へ増幅しないか |
| 更新操作の再送 | 既に作成・変更済みの対象を重ねないか |
tokenを増やしたり別アカウントへ要求を分散したりすることを、制限回避の自動対処にはしません。APIの利用ルールと必要な認証方式を守り、要求量や実行間隔を見直します。
残量確認のAPI自体も連打しない
現行のGitHub資料では、rate-limit状態を調べるendpointは一次枠を消費しなくても、二次制限に関係する場合があると説明しています。状態を知るために短い間隔で呼び続けるより、既に受け取った応答ヘッダーを活用します。
応答ごとのremainingは、常に一ずつ単調に減る数字とは限りません。別処理や処理region等の影響を考慮し、一つの値だけを厳密な残回数保証として使わず、403/429と待機指定を扱える設計にします。
再開後は成功と処理件数を確認する
許可された小さな要求から再開し、状態、待機時間、再試行回数、成功・失敗件数を記録します。書込みを伴う処理では、通信結果が不明な要求を、明確なrate-limit拒否と同じように再送しないでください。対象の状態と重複の有無を確認します。
完了時は、どの枠・どの要求集中が関係し、どの待機条件と要求量で再開できたかを残します。本文は公式仕様に基づく診断・設計手順で、実際のGitHub APIへの要求、制限再現、待機後の成功を検証した報告ではありません。