Google Sheets APIで429が返る場合、エラーになった操作名だけでなく、read／writeのどちらのquotaで、どのproject・利用主体へ要求が集まったかを確認します。セル更新の処理でも、その前の検索や取得を繰り返していれば、read側が先に上限へ達する場合があります。
この記事の対象はGoogle Sheets REST API v4です。Apps Scriptのquotaや、別のMCP toolsetの一呼出し当たりcostを、そのまま同じものとして扱いません。上限変更や課金操作ではなく、実際の要求量と再試行を整理する手順です。
目次
エラーのquota名と利用主体を記録する
HTTPステータス、エラー本文のquota情報、APIのmethod、時刻、project、認証主体を残します。service accountの秘密鍵やaccess tokenをログへ出さず、どの処理が使う認証か分かる識別情報だけを記録します。
表は横にスクロールできます
| 記録 | 見たいこと |
|---|---|
| quota metric・limit名 | readかwriteか、何の枠か |
| project | 同じprojectの別処理が使っていないか |
| 利用主体 | 一人・service accountへ集中していないか |
| methodと回数 | 取得、更新、metadata照会の実要求量 |
| 時刻・並列処理数 | 短時間に集中した原因 |
GoogleのUsage limits資料は、readとwriteについてproject単位、userごとのproject単位の毎分quotaを案内しています。ただし全projectが同じ上限とは限らないとも説明しているため、公開の代表値だけで自分の枠を確定せず、対象projectのquotaと利用状況を確認します。Google：Sheets API Usage limits（新しいタブで開く）
業務上の一操作とHTTP要求数を分ける
「一行を書いた」「一つの表を更新した」という業務上の単位と、APIへ送った要求数は違います。clientの便利な操作が、先にセルやmetadataを取得する場合もあるため、アプリの処理名だけをread／writeの判定に使いません。
表は横にスクロールできます
| 処理の例 | 確認する要求 |
|---|---|
| 一セルずつ確認して更新 | セル取得の反復、更新の反復 |
| 行を検索して追記 | 検索用の読取りと実際のappend |
| 定期同期 | 更新がない時の全件取得、同時起動 |
| 再試行付きclient | 自動再試行とアプリ側再試行の重なり |
機密を含まない形でmethod・要求先の範囲・時刻を観察し、処理全体の要求数を把握します。「書込みをbatch化したからreadは発生しない」とは限りません。別の処理が同じ認証主体とprojectを共有している場合も、合計の要求量へ目を向けます。
必要なrangeをまとめ、無駄な読取りを減らす
同じ目的で隣接する値を一つずつ読むより、必要な範囲を一度の取得へまとめられるかを確認します。更新も公式のbatch API等でまとめられる場合があります。ただし、values系とspreadsheets.batchUpdateでは指定内容や応答が異なるため、使用endpointに合う構造で扱います。Google：Batch requests（新しいタブで開く）
batch化は処理の意図を曖昧にしてよい理由ではありません。対象spreadsheet、sheet、range、値、request順序を残し、まとめた結果が同じ意味かを確認します。単に全シートを毎回取得するよう範囲を広げると、転送量や処理時間も増えるため、必要な列・期間を絞ります。
スケジュールが同じ秒に集中するなら、処理開始の分散やqueueによる要求量の制御も検討します。quotaのためにservice accountを増やす等の回避ではなく、不要な呼出し・重複起動・再読込みを減らす設計から見直します。
429の再試行は回数と待機上限を決める
Googleの現行資料は、時間枠のquota超過に対して指数backoffを案内し、待機にランダムな要素を加えて同時再試行の集中を避ける例を示しています。全workerが同じ間隔で一斉に再送すると、回復後も要求が集中するためです。
待機時間だけでなく、最大試行回数、最大待機、処理を止めて記録する条件を決めます。client libraryが既に再試行しているかも確認し、外側の再試行と掛け算にならないようにします。一定時間待てば必ず成功するとは保証せず、再び429なら要求量と対象quotaへ戻ります。
表は横にスクロールできます
| 設計する項目 | 残す記録 |
|---|---|
| 待機 | 使用した方針と実際の待機時間 |
| 打切り | 最大試行・最終エラー |
| 並列度 | 同時要求と他処理との共有 |
| 再送対象 | 読取りか、どの種類の書込みか |
書込みの結果不明を429と混ぜない
明確なエラー応答を受け取った場合と、送信後にtimeout等で応答を受け取れなかった場合は分けます。後者を「quotaで失敗したはず」と推測し、append等を繰り返すと、同じデータを重ねる可能性があります。
再送前に対象range、業務ID、既に反映された内容を、必要最小限のreadbackで確認します。固定rangeへ同じ値を再設定する操作と、行追加・相対的な変更も同じではありません。確認のための読取り自体がquotaを使うことを踏まえ、対象と頻度を絞ります。
完了は要求量とデータの両方で判断する
小さな検証で、対象quota、method別要求数、待機・再試行、成功件数を記録します。更新処理では、元件数、反映件数、業務IDの重複・欠落まで照合します。「429が出なくなった」だけでは、停止した処理がすべて反映された証明にはなりません。
本文は公式仕様に沿った診断・再試行設計で、特定projectのquota照会、上限変更、実APIでの429再現、書込みや回復を実施した報告ではありません。対象の設定や処理量が不明なら、その項目を未確認のまま記録して担当者へ渡してください。