🔄 「失敗したらもう1回」は壊れたリトライ――待つ・諦める・戻すの3節で書き直す

月商120万の自動化環境が、ある朝5本同時に止まっていました。ログを開いたら全部に同じ行が並んでいた。「失敗したのでもう1回実行しました」。もう1回も失敗。もう1回も失敗。最初の失敗から63分が経って、残っているのは最初の失敗とまったく同じ結果でした。

なぜこの仕組みが効くのか

スクリプトをはじめて書いたとき、リトライはこういう形をしていると思っていました。

for attempt in range(3):
    try:
        result = do_something()
        break
    except Exception as e:
        time.sleep(2)

これで合っています。ネットワークが一瞬切れた、サーバーが一時的に重くなった、そういう失敗なら確かにこれで直る。問題は「次の試行が成功するはずだ」という前提を、すべての失敗に同じく当てはめているところです。

稼働しているジョブが増えてくると、この前提が崩れる失敗が必ず現れます。

わたしが運用しているSNS自動化環境で、2026年8月8日から9日にかけての2日間で、5本のレーンから同時にリトライ修正が上がってきました。症状はどれも似ていましたが、原因はバラバラでした。

note-autolike のリライトが3日間ゼロ件でした。 最終成功は 2026-08-06T09:03:20Z。記事タイトルに58字上限のバリデーションがあるのに、生成プロンプトには字数制限が一言も書かれていなかったので、モデルは毎回63字のタイトルを返していた。3回投げて3回とも63字。4回目は試されることなく諦め処理に入ります。

ai-portraits の画像生成が63分空回りしていました。 モデレーションでリクエストが弾かれたとき、プロンプトを段階的に穏当にして再試行するフォールバックを3段実装していました。1概念あたり最大21分、3概念なら最大63分。実測では、対象コンテンツ自体がモデレーションの引っかかる原因のとき、Tierを下げても壁は動きません。3段全部を試したところで結果は1段目と同じでした。

browser-slot.sh はグローバル枠3本に対して1時間あたり18〜34本が起動を試みます。 1 runは14〜62分かかるので枠は常に埋まっている。修正前の実装は、acquire に失敗した瞬間に SKIP: global limit reached を出して exit 0 していました。ログに残っていた数字は、09時台9件・11時台8件・12時台12件が起動すらしていなかったというものでした。あるアカウントは当日2回ともskipで、いいねもフォローも0でした。

3つとも「もう1回」が実装されていましたが、どれも直っていません。

失敗の種類が違うからです。63字のタイトルは、同じプロンプトを同じモデルに投げれば同じ63字が返ります。決定論的な失敗です。モデレーションブロックも、コンテンツが原因なら条件を変えなければ何段試しても変わらない。枠の不足は、誰かが枠を空けるまで待つしかない。

この分類がないリトライ実装では、3種類の失敗がすべて「3回ループ→終了」という同一の処理に吸い込まれます。結果、直せた失敗も直せない失敗も同数カウントされて、最終的に同じ出口から出てきます。

逆側の壊れ方もあります。「失敗した」とログに残っているのに、実際には一過性の障害だったケースです。わたしの watch-arb スクリプトは、商品ページの取得に失敗すると extract_failed とだけ記録していました。翌朝画面を見ると「取得できない店が16件ある」と見える。実際には HTTP 429 が返っていただけで、同じ店を1件ずつゆっくり叩くプローバでは正しく取れていました。同期間中に確認した類似事象を並べると、同じ429がログ上で7つの別の名前で残っていました。

extract_failed と記録されていれば「この店の構造が特殊」と読みます。実際は「速く叩きすぎた」という問題で、翌日ゆっくり叩けば取れる。名前が間違っていたので、修正の方向を間違え続けていました。

これを整理すると、正しいリトライ設計は3つの問いに答えることに収束します。

(1) 待てば直るか。 (2) 何回で見切るか。 (3) 次の試行に何を変えて渡すか。

「失敗したらもう1回」はこの3つをすべて省略した実装です。上の5本が同時に止まっていた朝は、3つとも答えが書かれていませんでした。

月商120万の自動化環境は、毎日コードを書いているから動いているのではありません。自分が寝ている間に環境が自己修正して動き続けるから成立しています。その前提に立つと、リトライ設計の要件が変わります。「失敗しても次は直る」ではなく、「失敗の種類ごとに次の行動を決める」ことが要件になります。この設計がある実装と無い実装では、障害の復旧に自分が関与する必要があるかどうかが根本的に変わります。

全体の流れ

3つの問いをひとつの図で整理します。

失敗が発生した
      │
      ▼
┌─────────────────────────────────────┐
│ (1) 待てば直るか？                   │
│                                     │
│  枠不足 → 空くまで待つ               │
│  ネットワーク断 → バックオフして再試行 │
│  429 → Retry-After 優先で待つ        │
│  ログイン切れ → 待っても直らない      │
│  バリデーション違反 → 待っても直らない │
│  モデレーション → 段による（後述）    │
└─────────────────────────────────────┘
      │ 待っても直らない
      ▼
┌─────────────────────────────────────┐
│ (2) 何回で見切るか？                 │
│                                     │
│  回数上限 or 受付から3時間超 → 打ち切り │
│  まだ試せる → (3)へ                  │
└─────────────────────────────────────┘
      │ まだ試せる
      ▼
┌─────────────────────────────────────┐
│ (3) 何を変えて渡すか？               │
│                                     │
│  同じ内容を渡す → 決定論的失敗なら同じ結果 │
│  エラー内容を添えて渡す → 修正できる失敗なら回復 │
│  Tier降格（縦）→ 条件を穏当にして再試行  │
│  別課題に差し替え（横）→ 課題ごと変える  │
└─────────────────────────────────────┘

3節は順番に処理するのではなく、失敗の種類によって適用する組み合わせが変わります。ネットワーク断なら(1)だけで十分です。決定論的なバリデーション違反は(1)をスキップして(3)から入ります。モデレーションブロックは(1)のスキップ・(2)の閾値・(3)の変え方が全部関係します。

(1) 待つ — 実装の骨格

browser-slot.sh の修正で加えたコアは以下の形です。

BROWSER_SLOT_WAIT_SEC="${BROWSER_SLOT_WAIT_SEC:-600}"

wait_for_slot() {
  local waited=0
  while ! try_acquire_slot; do
    local jitter=$(( RANDOM % 31 + 15 ))   # 15〜45秒ランダム
    sleep "$jitter"
    waited=$(( waited + jitter ))
    if [[ $waited -ge $BROWSER_SLOT_WAIT_SEC ]]; then
      log "RESULT waited=${waited}s SKIP: slot timeout"
      return 1
    fi
  done
  return 0
}

再試行間隔を15〜45秒のランダムにします。 固定間隔にすると、枠を待っている全ジョブが同じ瞬間に殺到します（thundering herd）。ランダムジッタを入れることで、ジョブが互いにずれて自然に分散します。実測で、固定間隔では全ジョブが直列化してかえって詰まることを確認してから変更しました。

待機中はガードを掴みっぱなしにしません。 取得判定の一瞬だけロックを持って、判定後は必ず離します。ここを間違えると待機中のジョブが全部ロックを持ち合って全部止まります。

ログの RESULT 行に waited=600s を残します。 「600秒待ったうえで諦めた」と「即捨てた」は別の事象で、区別できないと後から評価できません。

BROWSER_SLOT_WAIT_SEC=0 で修正前の即skip動作と完全一致します。30本以上のlaunchdジョブがこのスクリプトを共有しているので、後方互換を維持しながら段階的に切り替えられるようにしました。

一方、一過性に見えて実は即再試行で直るケースもあります。Cloudflare の Authentication error [code: 10000] で3日連続ジョブが失敗していた案件があり、「OAuth が失効した → 人間の操作が要る」に見えていました。ところがシェルと launchd 最小環境の両方でプローブ5本を実走すると全て exit 0。失敗日のログを読み直すと、アクセストークン再発行直後の0.5秒後に同一トークンで別エンドポイントが 200 を返していた。トークン再発行直後の一過性 401 で、リトライが1回も無いのが真因でした。失敗率は 3/9日（33%）。「認証エラーだから人間案件」と即断すると、機械で直せるものを人間の待ち行列に積みます。

(2) 諦める — 終端を必ず置く

ai-portraits の Tier ラダーを例にします。モデレーションブロックのエラーには moderation_stage というフィールドがあります。output で止まったものはTier降格で通る実績がある。input から始まったものは、同期間中9試行全滅でした。

for tier in [1, 2, 3]:
    result = generate(concept, tier=tier)

    if result.get("moderation_stage") == "input":
        # input段 → Tierを変えても壁は動かない、残りをbreak
        log(f"input-stage block, skip remaining tiers for this concept")
        break

    if result.get("moderation_blocked"):
        # output段 → Tier降格で通る可能性がある
        continue

    if result.get("success"):
        return result

梯子を降りる価値があるかを1段目のエラー本文で判定します。 moderation_stage == "input" で break するだけで、63分の空走りが0分になります。同様に、gsheets_retry.py では 401/403/404 は即 raise するように設計されています。

RETRYABLE_HTTP = {429, 500, 502, 503, 504}

def sheets_call_with_retry(fn, max_attempts=3):
    delay = 2
    for attempt in range(max_attempts):
        try:
            return fn()
        except HttpError as e:
            if e.resp.status not in RETRYABLE_HTTP:
                raise  # 401/403/404 は即 raise — リトライで隠さない
            if attempt == max_attempts - 1:
                raise
            time.sleep(delay)
            delay *= 3  # 2秒 → 6秒（合計最大8秒）
        except (socket.timeout, ConnectionError, TimeoutError):
            if attempt == max_attempts - 1:
                raise
            time.sleep(delay)
            delay *= 3

「合計最大8秒を絶対に超えない」を先に決めます。 指数バックオフを回数で決めると、呼び出し側のスロット時間を静かに食います。秒数で上限を固定してから回数を逆算する順番が安全です。

回数だけで「諦める」を実装すると、時刻軸の障害に対応できません。kotonoha のジョブキューで 39時間 pending になる事故がありました。上限6回で中断しても requeue が成功するので失敗が一度も立たず、監視も鳴らず、利用者の画面は「作成中」のままでした。

修正後の判定式はこうなります。

function shouldGiveUpForQuota({ quotaHits, createdAtMs, resumeAtMs }) {
  const THREE_HOURS_MS = 3 * 60 * 60 * 1000;
  return (
    quotaHits >= 2 ||                                  // 2回目の上限
    resumeAtMs > createdAtMs + THREE_HOURS_MS          // 受付から3時間超
  );
}

「回数」と「受付からの絶対時刻」の二重で打ち止めを置きます。 事故当日の実値（受付 2026-08-19T00:36:57Z・再開 06:37:00Z）を境界ケースとしてテストに入れると、同じ事故は二度と通らないことが機械で保証されます。

(3) 戻す — 次の試行に変えた内容を渡す

note-autolike の例です。リライトが3日間ゼロ件だった原因は、同一プロンプトを3回投げ直すだけの実装でした。エラーを機械可読にして、2回目以降の試行には修正指示を付けて渡します。

// エラーに code / actual / limit を載せる
throw new ValidationError(`タイトルは1〜58字にしてください（実際: ${actual}字）`, {
  code: "title-too-long",
  actual,
  limit: 58,
});

// 2回目以降は修正指示を付けて投げる
function rewriteRetryInstruction(error) {
  if (error.code === "title-too-long") {
    return [
      `前回の出力は次の理由で不採用でした：`,
      `タイトルが${error.actual}字あり、上限の${error.limit}字を超えています。`,
      `同じ内容・同じ構成のまま、その点だけを満たす形へ直して、生JSONのみを再出力してください。`,
      `タイトルは絵文字込みで${error.limit}字以内（前回は${error.actual}字）に必ず収めてください。`,
    ].join("\n");
  }
}

async function askClaudeWithRetry(prompt, retries = 3) {
  let currentPrompt = prompt;
  for (let i = 0; i < retries; i++) {
    try {
      const result = await callClaude(currentPrompt);
      validateRewrite(result);
      return result;
    } catch (e) {
      if (e instanceof ValidationError) {
        // 決定論的な失敗 — スリープなし、修正指示を付けて即再試行
        currentPrompt = prompt + "\n\n" + rewriteRetryInstruction(e);
      } else {
        // プロセス系の失敗 — 30秒待つ
        await sleep(30_000);
      }
    }
  }
}

決定論的な失敗はスリープを挟まず即再試行します。 バリデーション違反に2秒待つのは、2秒を捨てているだけです。「待つ」と「直して投げ直す」を同じリトライで混ぜると、直せる失敗にも待ち時間を払います。失敗の種類で分岐して、スリープを入れる場所を選びます。

LLMへ返す修正指示は「機械の識別子」ではなく「人間語の指示＋現物の文字列」で渡します。"title-too-long" をそのまま渡すと3連敗します。「タイトルが63字あり上限の58字を超えています、58字以内に収めてください」と渡すと回復します。これは別のスクリプトで先に実証済みの事実です。

3節の全容はここで一旦止めます。次は各節の「壊れ方」と「直し方」を、5レーン同時障害から拾ったケース別に分解していきます。

実装の詳細

「リトライを書いた」は完了ではない ── フォルト注入を同じコミットに入れる

前半で設計した3節は、書いた時点では「動くはずのコード」でしかありません。間欠障害は再現手段がないので、リトライがその経路を実際に通るかどうかを確かめる方法がデフォルトでは存在しません。最初の4本の実装はそれで終わっていました。git diff を見て確認した気になって、完了にしていました。

実際に効いたのは、フォルト注入を実装本体と同じコミットに同梱することでした。

// watch-arb/collector/lib/api.mjs
let _failOnceRemaining = parseInt(process.env.WA_API_FAIL_ONCE ?? '0', 10);

async function req(path, opts = {}) {
  if (_failOnceRemaining > 0) {
    _failOnceRemaining--;
    throw new TypeError('fetch failed');  // 合成の障害、本番では絶対に発火しない
  }
  // ... 本来のfetch処理
}

カウンタはモジュールスコープで全 req 呼び出し共通です。プロセス起動後の最初のN回だけ、fetch を呼ぶ前に合成の TypeError を投げます。

完了条件は2本セットで必ず両方確認します。

• ① WA_API_FAIL_ONCE=2 で起動して api retry attempt=1/3 と 2/3 が出たうえで FATAL なく exit 0 で完走する
• ② 環境変数未設定なら retry ログが1行も出ない

②があることで「フォルト注入が本番に漏れていない」ことを同じコマンドで示せます。実測で出たログはこうなりました。

[INFO] api retry attempt=1/3 path=/api/collector/shops reason=fetch failed
[INFO] api retry attempt=2/3 path=/api/collector/shops reason=fetch failed
[INFO] 32件を ingest して exit 0

この型は watch-arb から zaiko-radar・lily-line-funnel・social-autolike と横展開して4本になりました。「リトライを書いた」は「フォルト注入込みで走ったところを見た」でなければ完了にしない、というルールに変わりました。

再試行する対象を1関数に閉じる

リトライを書くとき、最初に決めることは「何回試すか」ではなく「何を再試行するか」です。

// 判定を1関数に集約する
function isTransientStatus(status) {
  return status === 429 || (status >= 500 && status <= 504);
}

async function req(path, opts = {}) {
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    try {
      const res = await fetchWithTimeout(path, opts);
      if (!res.ok) {
        if (!isTransientStatus(res.status)) throw new HttpError(res.status);
        if (attempt === MAX_ATTEMPTS) throw new HttpError(res.status);
        await sleep(backoff(attempt));
        continue;
      }
      return await res.json();
    } catch (e) {
      if (!isNetworkError(e)) throw e;  // ネットワーク例外以外は即throw
      if (attempt === MAX_ATTEMPTS) throw e;
      await sleep(backoff(attempt));
    }
  }
}

401/403/404 を即 throw するのは省力化ではなく、別の事故を防ぐための設計です。権限エラーをリトライで包むと、同じリクエストを3回投げて3回とも同じ失敗が返ります。ログには「3回失敗した」とだけ残り、「権限が無い」という真因は埋もれます。

transient-failure-recorded-as-permanent.md で記録した「7つの名前で残った429」と逆向きの事故です。429が extract_failed に化けるのと同じ構造で、401/403 が「たまに遅い」に化けます。

isTransientStatus を1関数に出す理由は、判断が複数の呼び出し箇所に散ると場所ごとに微妙に違う定義が生まれるからです。gsheets_retry.py の RETRYABLE_HTTP = {429, 500, 502, 503, 504} という定数セットも同じ発想で、「どのステータスがリトライ対象か」という知識を1箇所に閉じています。

リトライを入れると例外の伝わり方が変わる

kotonoha に withRetry を実装した翌コミットで、副作用の修正が3件入りました。「機能を追加した」と思っていましたが、実際には「例外の伝わり方を変えた」変更でした。

変更前、purge() は 5xx が返っても後続の「手元の作業ディレクトリ30日掃除」まで処理が進んでいました。res.ok が false でも次の行へ進む実装になっていたからです。withRetry を入れて5xx の瞬間に throw するようになると、掃除のコードがそこで到達不能になります。実害は「作業ディレクトリが30日分蓄積する」という、定期的に手動掃除しなければ気づかない種類の静かな劣化でした。

async function purge(jobId) {
  try {
    await uploadResult(jobId);
  } catch (e) {
    log(`purge upload failed: ${e.message}`);
    // ここで throw しない — 置き場の失敗は記録して続行する
  }
  await cleanWorkDir();  // 例外の有無にかかわらず必ず走らせる
}

もう1件は setContentSafely で、1回目と2回目の再試行の間が0秒でした。リソース逼迫で落ちた直後に同条件で即再試行しても、圧力が残っている間は同じ結果になります。前半で「決定論的な失敗はスリープを挟まず即再試行」と書きましたが、その逆側です。資源逼迫が原因の失敗は、待たないとリトライに意味がありません。

試行回数は「失敗したとき何が起きるか」で非対称に設定しています。report()（結果報告）は失敗すると利用者の画面が「実行中」のまま永久に止まるので attempts=5、claim()（予約取得）は attempts=3。一律の回数はコストと被害の非対称を無視します。タイムアウトも操作の重さで分けていて、putObject と getStream は120秒、getText と listKeys は30秒です。タイムアウト設定のない fetch は「永久に吊られる」という最悪のリトライ不能状態を作ります。

ストリームを渡すとリトライできない

実装するまで意識していなかった制約があります。リトライ可能にするには、入力が「再実行可能」でなければなりません。

// NG: ストリームは一度消費したら再生できない
async function retryWithStream(stream) {
  for (let i = 0; i < 3; i++) {
    await fetch(url, { body: stream });  // 2回目はストリームが空
  }
}

// OK: Buffer か string に限定する
async function retryWithBuffer(buffer) {
  for (let i = 0; i < 3; i++) {
    await fetch(url, { body: buffer });  // 何度でも同じデータを送れる
  }
}

putObject に渡す body を Buffer か string に限定しました。型制約をコメントで残しておかないと、後から呼び出し側がストリームを渡して「リトライが動いているのに毎回失敗する」バグになります。ストリームをリトライに渡すと2回目以降は空のボディを送り続けます。エラーも出ずに毎回失敗します。

---

私が詰まった話

防御のために置いた定数が、成功率0%の壁になっていた

outreach-multi の DM 受信箱パース処理で、unparsable json というエラーが毎日出ていました。セレクタが壊れたか、JSON の構造が変わったかと疑って3日間修正し続けました。

実態は、受信箱取得のコードに text.slice(0, 400_000) という行がありました。巨大なレスポンスが来たときにメモリを保護するために書かれた上限でした。IG の DM 受信箱の実サイズを計測したら 512,558文字 でした。上限が 400,000 なので、毎回必ず途中で切れます。切れた JSON は JSON.parse で毎回必ず失敗します。成功率は0%です。

3日間同じ失敗を見続けていたのは、text.slice の行を忘れて「パースに失敗している → 構造が壊れた」と読んでいたからです。症状が出始めたのも「今日から」ではありませんでした。受信箱のサイズが 400,000字を超えた日から静かに失敗し始めて、ある日気づいたら通算0件になっていた形です。

修正は page.evaluate の中で JSON.parse まで完了させ、失敗したときだけ先頭300字を診断用に返す形に変えました。

この件から得た設計ルールは「上限を置くなら、上限に当たったこと自体をログに出す」です。text.slice はサイレントに切り落とすだけで、切れたことを誰にも知らせません。防御の定数がその定数を超えた瞬間から恒久的な失敗に変わっていても、ログには何も残りません。

quarantine が永久ループになっていた

unfollow-core.js のアンフォロー処理に、3回失敗すると7日間の保留（quarantine）に入る仕組みがありました。

問題は「quarantine から復活したらどうなるか」です。復活したアカウントは候補リストに戻ります。再度3回失敗すると、また7日間の保留に入ります。これが無限に回ります。

候補が 2,605件あって、scanned: 8 / unfollowed: 2 という数字を見て2週間悩みました。候補がほぼ処理されていない。「なぜ進まないのか」を調べたら「同じアカウントが quarantine に入っては出るを繰り返していて、前に進んでいない」でした。

ログには circuit-break と出ていました。circuit-break が機能しているのに実行数が増えないのは矛盾します。もっと早く気づけたはずでしたが、「circuit-break が動いている = 保護されている」と読んでいたので疑いませんでした。

修正は、累計失敗回数（UNFOLLOW_GIVEUP_FAILS = 6、quarantine 失敗閾値の2倍）に達したアカウントを台帳から物理削除することでした。

「保留」は溜まるだけで減りません。 捨てる終端を必ず置かなければ、台帳は処理できないアカウントで埋まり続けます。ただし捨てる前に「自分の処理が正常に動いているか」の確認が先です。セッションが切れていただけで、正常なアカウントを全部捨ててしまう逆事故があり得ます。kotonoha のページに書いた「捨てる前に自分の正常性を確認する」という原則がここにも適用されます。

監視が39時間鳴らなかった

kotonoha のジョブが39時間ずっと「作成中」のまま止まっていました。監視は一度も鳴りませんでした。ジョブは失敗として記録されていませんでした。

原因は「回数を状態に持っていないリトライには、打ち止めが置けない」でした。

ジョブがクォータ上限に当たると requeue で pending に戻します。戻したジョブは「何回目か」というカウンタを持っていませんでした。7回目のジョブも1回目のジョブも実装から区別できません。requeue が成功するので失敗も立ちません。監視の閾値にも当たりません。利用者の画面には「作成中」が延々と表示され続けます。

修正は2段階でした。まず「回数を状態に持たせる」。次に「回数と受付からの絶対時刻の二重で打ち止めを置く」。前半で示した shouldGiveUpForQuota 関数を境界ケース付きのテストに通すとき、事故当日の実値（受付 2026-08-19T00:36:57Z・再開予定 06:37:00Z）を1ケース入れました。同じ事故は二度と通らないことが機械で保証されます。

回数だけで打ち止めを置いていると「1回目だが再開が12時間先」を通してしまいます。時刻だけだと「再開は短いが上限が連続している」を通してしまいます。今回の事故は時刻条件の側で1回目に捕まる形でした。二重にした意味が実データで測れた件です。

「ワーカーが待つ」と「そのジョブを諦める」は別の判断です。クォータは待てば直る失敗なのでワーカーは待ちます。でも利用者を3時間以上待たせる根拠にはなりません。

「認証エラー」と即断して3日間人間待ちにしていた

com.lily.line-pdca が Cloudflare の Authentication error [code: 10000] で3日連続止まりました。認証エラーなので「OAuth が失効した、手動で wrangler login が要る」と判断しました。環境変数の設定漏れも疑いました。

確かめる前に「人間のGUI操作が要る案件」として分類したのが間違いでした。

実際に shell と launchd 最小環境の両方で wrangler whoami・kv key list・deploy --dry-run を実走すると全て exit 0 でした。出力バイト数まで同一（1,516 bytes）。失敗日のログを読み直すと、アクセストークンを再発行した 0.5秒後 に KV keys が 401 を返していました。その同じトークンで0.5秒後の /user は 200 を返していました。トークン再発行直後の一過性 401 で、リトライが1回もないのが真因でした。

失敗率は 3/9日（約33%）でした。毎日出ない、でも3日に1回は出る。この頻度が「人間案件に見える」原因でもありました。

判断を変えた基準は「同じ手順を今もう一度叩いたら通るか」を実際に叩いて確かめることでした。エラーの種類（401・Authentication error）だけで「絶対に直らない」と分類しない。transient-failure-recorded-as-permanent.md に記録した「429が7つの名前で残っていた」と同じ型で、今度は「認証エラー」という名前が一過性の失敗を人間案件に見せていました。

この件以降、認証エラーが出たらプローブを1本走らせてから判断するルールに変わりました。「機械で直せるものを人間の作業待ちキューに積まない」の前提は「機械で叩いて確かめた」です。確かめないまま即断するのは、叩かずに「直らない」と決めつけているのと変わりません。

つまずきポイント

前段で取り上げた個別事例の裏にある構造的なパターンをまとめます。「詰まった場所の名前」が違うだけで、根っこは同じ型です。

失敗を「ひとつの名前」に圧縮して記録する

watch-arbの商品ページはextract_failed、bootstrap実行はFATAL、DM受信箱はunparsable jsonと記録されていました。3つとも実際の真因はHTTP 429です。transient-failure-recorded-as-permanent.mdに記録したこの事象を整理すると、同期間中で同じ429が7種類の別名で残っていました。名前の時点でHTTPステータスが消えると、「待てば直る」なのか「構造を直す必要がある」のかの判断ができなくなります。修正は1行です。記録する前に429/503 → rate_limited / 401/403 → auth_error / それ以外 → extract_failedと分類します。この3分岐が「待つ・諦める・戻す」の分岐の手前にある前提条件です。

エラー本文を捨てている

ai-portraitsのgenerate.pyがcodex execのstdout/stderrを捨てていたため、画像が出なかった理由がmissingとしか残りませんでした。moderation_blockedもsafety_violations: ["sexual"]も見えなければ、Tier降格で回復するのかinput段で即打ち切るべきかの判断が立ちません。エラーを保持しない実装では「待つ/諦める/戻す」の3節がそもそも成立しないので、エラー保持は設計の前提であって機能追加ではありません。

moderation_stageを確認せずに全Tierを試す

moderation_stage: inputで止まった概念は、T1からT3まで全段試して9試行全滅でした。moderation_stage: outputで止まったものはTier降格で通る実績があります（partial 01_feet_up_windowはT2、03_legs_on_bed_topdownはT3）。T1のmoderation_stageフィールド1語で「梯子を降りる価値があるか」が決まるのに、フィールドを読まずに全段を試すと1概念あたり最大21分、3概念で最大63分が無駄になります。「安全側フォールバックが何段あるか」より「1段目のエラー本文で降りる価値があるか」を先に判定します。

降り先の容量を測らずに配線する

social-autolikeのfollow-source-followersでフォールバックを追加する前に、UIモーダルのfollowing側が408件/63秒で伸びるのに対してfollowers側が12件で止まることを先に実測しました。容量がある側だけをフォールバックに採用したのが理由です。測らずに配線すると、容量のない降り先に全トラフィックが流れて「降り先を追加したのに成功率が変わらない」という状況になります。outreach-multiのpk解決も、IGが70件前後で絞るという既知の壁を織り込んで1run 30件制限にしています。

恒久的な失敗を「あと1回」の枠に数える

outreach-multiのDM送信でno メッセージ button（DM不可の設定）が返ると、exhausted after 3 attemptsに乗って送信枠を1件あたり3回分消費していました。相手のアカウント設定はこちらがリトライしても変わりません。sent.jsonlのreasonフィールドを読んで、no メッセージ button / profile gone / このページは存在しませんを含む宛先はpermanentlyFailed Setに入れ、shouldSkip()でexhaustedの手前に判定を置きます。これは前段で触れた「一過性を恒久として記録する逆向きの事故」と同じ根で、失敗の分類の設計がリトライ回数の設計より先に要ります。

429のあとも同じ速度で叩き続ける

social-autolikeのig-3は0.3〜0.5秒間隔で17ソースを数秒で撃ち込んで14時間ゼロ成果でした。429を受けた後も間隔を変えなければ、制限中に同じリクエストを積み上げて自分でスロットリングを延長します。retry-and-giveup-design.mdに記録した修正では、3連続429でそのプロセスのAPI呼び出しを打ち切るラッチと、429を1度でも見た店のconcurrencyを1に落とす設計を入れています。待ってから再試行するだけでなく、速度そのものを落とすことがセットです。

リトライが2層に重なっている

watch-arbのingestShopが独自に3回ループを持ち、req()側にも3回ループがありました。最悪3×3=9回になり、ログに「retry attempt 3/3」が2度並んで、上限がどこにあるのか、今何回目なのかが読めません。フォルト注入を入れても「どちらの層が動いているか」が分からなくなります。修正はingestShop側の独自ループを削除してreq()の1層に一本化しました。呼び出し側は即throwするだけにします。

フォールバックの成功を打ち切りカウンタに数える

「3連続429でAPI呼び出しを打ち切る」ラッチが、UIフォールバックが成功した件もカウントに含めていました。逃げ道を作っても3件で止まっていました。打ち切りカウンタは「全経路が失敗したとき」だけ増やします。フォールバック先で成功した件は、メインの失敗カウントに載せません。

「取れなかった（異常）」と「取りに行く時間がなかった（正常な打ち切り）」を同じゼロ件で判定する

follow-source-followersはソース取得だけで時間予算を使い切って候補ゼロ件になった場合、既存の「全ソース取得失敗→誤操作防止で停止」経路に入ってしまいます。取れなかったのか時間がなかっただけなのかは別の事象です。同じゼロ件で判定すると毎日誤報が鳴り、本物の失敗を見分けられなくなります。time-budgetという別出口を用意して区別します。

諦める判定式をcatchブロックにベタ書きする

打ち止めの条件がcatchの中に書かれていると、境界ケースのテストに載せられません。純粋関数に出すと事故当日の実値を1ケース入れられ、同じ条件が二度と通らないことを機械で保証できます。ロジックがcatchの中にある限り、テストは「たまたまケースが通らなかった」状態で合格します。

エラーメッセージに機械可読な情報が載っていない

ValidationErrorを文字列だけで投げると、再試行時に「何が悪かったか」をコードから取り出せません。2回目以降に同じプロンプトを投げると同じ結果になるのは「戻す」が実装されていないからで、code: "title-too-long", actual: 63, limit: 58のような構造を載せると修正指示を動的に組み立てられます。LLMへ返すときは識別子（"title-too-long"）でなく人間語の指示文と実測値を渡します。識別子をそのまま渡すと3連敗します。

---

ベストプラクティス

5レーン同時障害から蒸留したルールを列挙します。数が多いですが、全部「実際に詰まったから入れた」ものです。

① 失敗は記録する前にHTTPステータスと例外の型で分類する

429/503 → rate_limited / 401/403 → auth_error / それ以外 → 処理系エラー。この3分岐を先に置くだけで、画面に出る「失敗している店の一覧」の意味が変わります。watch-arbはこの分類を加えた後、shops.last_errorの文言も「レート制限で取得できず」と「構造が取れない」に分けました。

② リトライを書いたら、フォルト注入を同じコミットに入れる

let _failOnceRemaining = parseInt(process.env.WA_API_FAIL_ONCE ?? '0', 10);
// 起動後の最初のN回だけ合成のエラーを投げる

完了条件は2本セットです。=2でretry attempt=1/3と2/3が出てexit 0で完走すること、未設定なら retry ログが1行も出ないこと。②がないと「フォルト注入が本番に漏れていない」ことを同じコマンドで確認できません。

③ 打ち止めを「回数」と「受付からの絶対時刻」の二重で置く

回数だけだと「1回目だが再開が12時間先」を通します。絶対時刻だけだと「再開は短いが上限が連続している」を通します。kotonohaの事故は時刻条件の側で1回目に捕まる形でした（受付2026-08-19T00:36:57Z・再開06:37:00Zが受付+3時間の外）。二重にした意味が実データで測れた件です。

④ 待ちの合計上限を秒で先に決め、回数を逆算する

gsheets_retry.pyは「合計最大8秒を絶対に超えない」を依頼文に固定してから、2秒→6秒（3回）を逆算しました。指数バックオフを回数で先に決めると、呼び出し側のスロット時間が静かに侵食されます。

⑤ 401/403/404は即throwしてリトライで隠さない

if e.resp.status not in RETRYABLE_HTTP:
    raise  # 権限エラーは即 raise

権限エラーをリトライで包むと「3回失敗した」とだけ残り、「権限がない」という真因が埋もれます。transient-failure-recorded-as-permanent.mdで記録した「429がextract_failedに化ける」と同じ構造で、今度は401が「たまに遅い」に化けます。

⑥ moderation_stageで梯子を降りる価値があるか判定してからTierを試す

if result.get("moderation_stage") == "input":
    log("input段の拒否。残りTierをbreak")
    break

1行加えるだけで63分の空走りが0分になります。outputで止まったものはラダーを回す価値があります。inputで止まったものは概念ごと捨てて次に進みます。

⑦ リトライの層を1箇所に集約する

呼び出し側が独自ループを持ちライブラリ側にも再試行があると最悪N×M回になります。重複を見つけたら外側のループを削除してreq()の1層に一本化します。

⑧ 降り先の容量を測ってから配線する

フォールバックを追加する前に、実測で「この降り先が何件まで返すか」「どこで詰まるか」を確認します。容量のない降り先に全トラフィックを流しても成功率は変わりません。

⑨ 恒久的な失敗は永続リストに1回で記録して除外する

no メッセージ button / profile goneのような相手側の設定に起因する失敗は、リトライ回数を消費する前に除外します。shouldSkip()の判定をexhaustedの手前に置きます。

⑩ 「今もう一度叩いたら通るか」を実際に叩いてから人間案件に分類する

Cloudflare Authentication errorを「OAuthが失効した」と即断して3日間人間の待ち行列に積んでいました。shell と launchd 最小環境の両方でプローブを実走すると全てexit 0でした。エラーの名前だけで「絶対に直らない」と分類しない。確かめてから判断します。

⑪ 上限定数が当たったこと自体をログに出す

text.slice(0, 400_000)はサイレントに切り落とすだけでした。防御の定数が恒久的な故障の引き金になっていても、ログには何も残りません。JSON.parseまで内部で完了させ、失敗したときだけ診断用に先頭300字を返す形にすると、「切れた」という事実が記録に残ります。

⑫ リトライ導入後は例外の伝播範囲の変化を確認する

withRetryを入れると「握りつぶし→throw」に変わった箇所の下流にある必須処理が到達不能になることがあります。リトライは機能の追加ではなく、例外の伝わり方を変える変更です。下流に「失敗しても必ずやるべきこと」がある箇所は個別に囲み直します。

⑬ 資源逼迫が原因の失敗は、待ってから再試行する

setContentSafelyの再試行間隔がゼロ秒では、高負荷で落ちた直後に同条件でもう一度落ちます。決定論的な失敗はスリープなし即再試行が正解ですが、その逆側として、資源を待たないとリトライに意味がありません。失敗の種類でスリープを入れる場所を選びます。

⑭ 諦める判定式を純粋関数に出してテストに事故当日の実値を入れる

shouldGiveUpForQuota({quotaHits, createdAtMs, resumeAtMs})へ切り出して、受付2026-08-19T00:36:57Z・再開06:37:00Zを1ケースとして入れると、同じ事故は二度と通りません。catchブロックにベタ書きされた判定は境界ケースをテストできません。

⑮ 待った事実・諦めた事実・打ち切った事実をログの1行に残す

waited=600s SKIP: slot timeoutとSKIP: global limit reached（即捨て）は別の事象です。どちらも同じ「SKIP」に見えると、「枠の競合が増えた」なのか「もともと即捨てしていた」なのかを後から区別できません。投資した待ち時間は数値でログに出します。

---

まとめ

「失敗したらもう1回」と書いたとき、そのコードには3つの問いの答えがありません。待てば直るか、何回で見切るか、次の試行に何を変えて渡すか。この3つが揃っていない実装は、決定論的な失敗の前で資源を焼き続けて止まります。

5レーンが同時に止まった朝に並べて気づいたのは、障害の復旧に自分が関与する必要があるかどうかが、この設計の有無でほぼ決まるという点です。設計があれば、スクリプトは失敗の種類ごとに次の行動を自分で決めます。設計がなければ、同じ失敗が3回記録されるだけで、翌朝も同じ場所に詰まります。

月商120万の自動化環境が毎日動いているのは、コードを毎日書いているからではありません。失敗が正しく分類されて、機械が自分で回復するから成立しています。その前提に立つと、リトライ設計は「後から加える機能」ではなく、最初の実装に含まれているべきものです。

「リトライを書いた」は、「フォルト注入込みで走ったところを見た」で完了にします。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。

📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍
• AI導入・自動化の相談と実装テンプレ7本の配布は 公式LINE から💬

皆さんの ❤️ やシェアが励みになります！