無人で繰り返す処理が API を乱打しない設計 — 失敗打ち切りガード実装手順

何のための指示書か

cron / スケジュールトリガー / ジョブワーカーのように無人で繰り返し走る処理に、 「恒久的に失敗するレコードが毎回リトライされ続ける」構造を作らないためのチェックリストと実装パターン。

これを怠ると、外部 API を高頻度で叩き続けて API 提供元からレート制限・アカウント凍結を受ける。 実際に「クラウドストレージをデータ受け渡しに使って AI にコード修正をラリーさせ、 ストレージ API を叩き続けた結果アカウントが凍結された」という事例が報告されている。

対象読者は AI コーディングエージェント。そのまま読ませて実装させられる粒度で書いてある。

---

判定基準（これだけ覚えればよい）

このレコードが永久に失敗し続けたら、何回リトライされるか。 答えが「無限」なら設計が間違っている。

無人実行の入口を1つずつ辿り、この問いに数字で答えられるようにする。答えられない箇所が事故の種。

---

チェックリスト

1. 失敗レコードは必ず「前に進む」

処理済み印・エラー状態・失敗カウンタのいずれかを必ず永続化する。 「成功したら完了印を書く」だけの実装は、失敗したレコードが毎回選び直される。

2. 失敗回数の上限と指数バックオフを持たせる

• 上限（例: 5回）に達したら恒久スキップし、ログに残す
• 間隔は指数的に伸ばす（例: 5分 → 15分 → 1時間 → 3時間 → 6時間）

3. 試行カウンタは「処理の前」に保存する

最重要かつ最も間違えやすい点。 後から書くと、実行時間上限（サーバーレスのタイムアウト、スケジュール実行の実行時間制限）で プロセスが殺されたときにカウンタが増えず、無限ループが残る。

4. リソース生成を冪等にする

ファイルコピー・フォルダ作成・レコード作成は、同名の既存を先に探して再利用する。

「生成 → 長い処理 → 最後に完了印」の順序が最も危険。 生成と完了印の間で落ちると、失敗のたびに孤児リソースが増える。 コード上で「生成する行」と「完了印を書く行」の距離を必ず確認すること。行数が離れていたら危険信号。

5. レート制限エラーは指数バックオフ＋回数上限で扱う

• 再試行するのは一時的な失敗だけ（429 / 500 / 503 / 接続リセット / タイムアウト）
• 権限エラー（401 / 403）や 404 は即座に再スローする。権限が無いものを5回叩き直すのは無意味で、かえって負荷になる
• フォールバック経路が失敗時にコール数を増やしていないかを確認する（一括取得の失敗 → 1件ずつ再取得、は増幅する）

6. 無制限ページネーション・全件毎回取得を避ける

増分取得かチェックポイントを持たせ、1実行あたりのコール数に上限を置く。 全件取得が必要な設計なら、通常運用で到達しない安全弁（最大ページ数）を入れる。

7. キューの結果ファイル・ログを同じ場所に溜め続けない

毎回の一覧取得が重くなる。日次の housekeeping で古いものを退避・削除する。

8. 恒久スキップからの「復帰手段」を必ず用意する

上限で止める実装だけ入れて復帰経路を作らないと、原因を直しても永久に止まったままになる。 ガードが別の詰まりを生む。次の3つを運用コマンドとして公開する。

• 詰まっているレコードの一覧（読み取り専用）
• 特定レコードのカウンタリセット
• 全件のカウンタリセット

9. 恒久スキップのログは頻度を絞る

毎分実行の処理で毎回エラーログを出すと、1日1,440行出てログが実質使えなくなる。 1時間に1回だけ出す（最終ログ時刻も一緒に永続化する）。

---

実装パターン

失敗カウンタ + バックオフ（擬似コード）

BACKOFF_MINUTES = [5, 15, 60, 180, 360]
MAX_ATTEMPTS = 5

function backoffMs(n) {
  i = min(max(n, 1), len(BACKOFF_MINUTES)) - 1
  return BACKOFF_MINUTES[i] * 60 * 1000
}

for record in candidates:
    key = "FAIL_" + record.id
    fail = loadJson(store, key) or { n: 0, lastMs: 0, lastLogMs: 0 }

    // 恒久スキップ（ログは1時間に1回だけ）
    if fail.n >= MAX_ATTEMPTS:
        if now - fail.lastLogMs >= 3600_000:
            logError(record.id + " は " + fail.n + " 回失敗したため停止。復帰は resetFailures コマンド")
            fail.lastLogMs = now
            saveJson(store, key, fail)
        continue

    // クールダウン中
    if now < fail.lastMs + backoffMs(fail.n):
        continue

    // ★ 試行の「前」に保存する（タイムアウトで殺されてもカウンタが残る）
    fail.n += 1
    fail.lastMs = now
    saveJson(store, key, fail)

    try:
        process(record)
        deleteKey(store, key)      // 成功したらカウンタを消す
    catch e:
        logWarn(record.id + " failed: " + e)   // カウンタは既に加算済み

注意: スキップした要素で処理を打ち切らないこと。 「1回の実行で1件だけ処理して抜ける」設計の場合、continue（次の候補へ）と break（実行を終える）の位置を間違えると、詰まった1件の後ろにある正常なレコードが永久に処理されなくなる。

冪等なリソース生成

// ✗ 悪い例: 失敗のたびにコピーが増える
copy = template.makeCopy(name, folder)

// ✓ 良い例: 既存を再利用する
existing = folder.getFilesByName(name)
copy = existing.hasNext() ? existing.next() : template.makeCopy(name, folder)
if existing_was_found: log("既存を再利用: " + name)

一時的エラーだけ再試行する共通ヘルパー

TRANSIENT = /quota|rate limit|rateLimit|RESOURCE_EXHAUSTED|userRateLimitExceeded|ECONNRESET|ETIMEDOUT/i

async function withRetry(fn, { tries = 5, label = "call" } = {}) {
  for (i = 0; i < tries; i++) {
    try { return await fn() }
    catch (e) {
      code = e.code ?? e.status ?? e.response?.status
      transient = code === 429 || code === 500 || code === 503 || TRANSIENT.test(String(e.message))
      if (!transient || i === tries - 1) throw e      // 権限エラー等は即スロー
      waitMs = min(60_000, 1500 * 2**i + 500 * (i + 1))
      logWarn(`[retry] ${label} attempt ${i+1}/${tries} — ${waitMs}ms backoff`)
      await sleep(waitMs)
    }
  }
}

共通ヘルパーは1箇所に置き、全ての外部 API 呼び出しから使う。 各ファイルにローカル定義が散ると、必ず「使い漏れ」が出る。 既に動いている実績のあるバックオフ実装がある場合は、無理に統一せずそのままにする（回帰リスクの方が大きい）。

キューは「読んだ直後に消す」

payload = read(item)
markConsumed(item)     // ★ 処理の前に消す。失敗しても再実行されない
result = execute(payload)   // 失敗しても item は戻ってこない
writeResult(result)

あわせて多重起動の排除（ロックを 0ms タイムアウトで取り、取れなければ即 return）を入れる。

---

コスト面の副作用（従量課金の CI / 実行基盤を使う場合）

多くのマネージド実行基盤はジョブごとに分単位で切り上げ課金する。 そのため 「数秒の処理を高頻度で回す」ジョブが最も割高になる。

実測例: 8秒の処理を月766回 → 実計算は約1.7時間なのに 766分課金される。 同様の短時間ジョブが3本あると、実処理3時間弱で1,200分（無料枠超過分がそのまま費用）になる。

対策: 短時間・高頻度のジョブを1本に統合してステップとして順次実行し、起動オーバーヘッドを1回に集約する。 頻度そのものを落とせるかは業務要件次第だが、統合は機能を変えずに効く。

予算上限の到達アラート（75% / 90% / 100%）は常に有効にしておく。 上限に達して実行が止まると、ジョブが起動しないためログが空になり、コードの不具合と区別しにくい。 「ステップの失敗が無いのに失敗している」ときは課金・権限側を疑う。

---

検証（実装後に必ず行う）

1. 無人実行の入口を全て列挙し、各入口について「永久に失敗するレコードは何回リトライされるか」を数字で答える
2. 恒久スキップに入れたレコードを、用意した復帰コマンドで実際に解除できることを確認する
3. 一覧コマンドを実行し、想定どおりの形（レコード識別子・失敗回数・最終試行時刻・停止中フラグ）が返ることを確認する
4. 人が読む識別子を併記する。内部 ID だけを返すコマンドは、読む側が毎回引き直す手間を負う
5. 「生成する行」と「完了印を書く行」の距離をコードで確認し、間に外部 API 呼び出しや長時間処理が挟まっていないか見る

「たぶん動く」で終わらせず、実際に実行して出力を目視すること。