「エラーが発生しました」としか出ないとき、まず疑う 429 と確かめる順番

壁紙アプリの説明文を多言語に整えていた夜のことです。エージェントに作業を頼んで席を立ち、戻ってくると、画面には「エラーが発生しました」とだけ表示されていました。理由も、直し方も、書かれていません。

最初のうち、私はこの一文を「何かが壊れた」合図だと受け取っておりました。アプリを再起動し、プロジェクトを開き直し、同じ依頼を三度送りました。結果は芳しくありませんでした。四度目に送る前に手を止めてログを開いてみて、原因が壊れた何かではなく、ただ上限に当たっていただけだと分かったのです。

最初にお伝えしたいのは、原因の書かれていない汎用エラーの裏には、利用上限（HTTP ステータスコードの 429）が隠れていることがある、という点です。そして上限に当たっているなら、直す作業は要りません。必要なのは、待つことと、連打をやめることです。

汎用エラーと 429 の見分けがつきにくい理由

429 は「短い時間にリクエストが多すぎます」という意味のコードです。サービス側が、これ以上は受け付けないと一時的に断っている状態を指します。

本来なら「上限に達しました。しばらくしてからお試しください」と表示されるのが親切です。ところが、画面に出る文言は、裏側で起きたことをそのまま映すとは限りません。上限の応答も、通信の失敗も、認証の期限切れも、同じ「エラーが発生しました」にまとめて表示される場面があるのです。

画面の文言だけでは区別がつかないのです。ここが、最初の一歩を迷わせる原因なのかもしれません。

確かめる順番は、軽い順に四つ

闇雲に設定を触るより、負担の軽い確認から順に進めるほうが、結果として早く片づきます。私が使っている順番をお伝えします。

1. 画面のエラー表示に、「詳細」や「デバッグ情報」を開くボタンがないかを見ます
2. 開けた情報の中に、429、RESOURCE_EXHAUSTED、quota、rate limit といった言葉がないかを探します
3. 別の単純な依頼（「こんにちは」だけ）を一度だけ送り、通るかを見ます
4. 利用状況の画面で、上限に近づいていないかを見ます

画面名や場所は、版によって呼び方が変わります。ここでは「エラー表示の近くに詳細を開く入口があれば、まずそこを見る」という考え方だけ持ち帰っていただければ十分です。

1. 詳細を開いて、言葉を探す

詳細に表示された長い文章は、読もうとすると手が止まります。読まずに、探します。

ブラウザやエディタの検索機能で、次の言葉を順に当ててみてください。

429
RESOURCE_EXHAUSTED
quota
rate limit
exceeded

どれかが見つかれば、上限に当たっている可能性が高いと言えます。一方で、401、403、expired、unauthorized が見つかるなら、疑うべきは上限ではなくサインインの状態です。timeout、ECONNRESET、network なら通信です。

見つかった言葉が、そのまま次の一手を決めます。

2. 単純な依頼を一度だけ送る

詳細が開けない版もあります。その場合は、短い依頼を一度だけ送ってみます。

「こんにちは、と返してください」くらいで構いません。ここで返事が来るなら、アカウントも通信も生きています。長い作業の途中で上限に触れた、という読みが強まります。

大切なのは一度だけという点です。ここで連打を始めると、次の章の落とし穴に落ちます。

やってはいけないのは、連打と再試行の自動化

上限に当たっている最中に、同じ依頼を何度も送ると、待ち時間が延びることがあります。サービスによっては、断られた後の再試行まで数えて、次に受け付けられるまでの時間を長くするからです。

私は一度、これで余計な時間を使いました。急ぎの作業だったので、戻るたびに再送を重ね、結果として半日ほど何も進まない状態になったのです。

いまは次の線引きにしています。いま思えば、焦りが一番の原因でした。

断られたら、押す回数を減らして、待つ時間を増やす。

具体的には、次のように動きます。

• 最初の再送は、数分空けてから一度だけにします
• それでも同じなら、間隔を倍にして一度だけ試します
• 三回続けて同じなら、その日の作業を切り替えます（ローカルでできる下調べや、文章の下書きなど）

待つあいだに手を動かせる仕事を、あらかじめ一つ決めておくと、気持ちの面でもずいぶん楽になります。

上限が原因だったときの次の一手

上限だと分かったら、考えるべきことは二つです。

一つは、どの作業が大量に消費したのかを振り返ることです。巨大なファイルを一度に読ませた、複数のエージェントを並べて走らせた、同じ質問を何度も作り直した——心当たりのある操作が見つかれば、次から分割や間引きができます。

もう一つは、待つ以外の選択肢があるかを確かめることです。使っているプランの上限、別のモデルへの切り替え、作業を翌日に回す判断。どれを選ぶかは、締め切りの重さで変わります。

個人開発の現場では、急ぎでない作業を朝のうちに流し、急ぎの作業の分を残しておく、という使い分けが効きます。私自身は、夜に重い依頼をまとめて走らせるのをやめてから、汎用エラーに出会う回数が減りました。

上限ではなかったときのために

詳細を探しても 429 に関する言葉がなかった場合は、別の原因です。

何も見つからないときは、無理に原因を決めつけないことにしています。分からないものは分からないままメモに残し、後で同じ症状が出たときに突き合わせられるようにしておきます。

次にやること

次に汎用エラーを見たら、再起動する前に、詳細を開いて 429 を検索してみてください。

それだけで、「壊れた」のか「待てばよい」のかが分かります。私もこの一手を覚えてから、画面の前で慌てる時間が、ほんの少し短くなりました。