Claude APIのエラー処理：再試行・修正・保留を分ける

再送で変わらない失敗を切り離す

入力形式や認証情報に問題がある場合、同じ要求を再送しても解決しないことがあります。利用者が修正する入力か、運用側が確認する設定かを区別します。内部の認証情報をそのまま画面へ出さず、必要な案内だけを返します。

エラーコードやヘッダーの意味は最新の公式仕様と照合します。表示用の文章と内部のエラー種別を分けると、文言が変わっても復旧の制御が影響を受けにくくなります。

レート制限には待つ仕組みを用意する

短時間に再送を集中させると、制限を長引かせる可能性があります。再試行の間隔、上限回数、要求の有効期限を設け、必要なら待ち行列へ入れます。利用者には処理中なのか失敗したのかを示し、何度も押すことが重複要求にならないようにします。

複数のサーバーがある場合、一台だけの制御では全体の送信量を把握できません。共有する利用枠と、利用者ごとの公平性を合わせて考えます。

成功不明の外部操作を別に扱う

生成要求の失敗と、ツールによる書き込みの結果不明は同じではありません。更新処理の応答がない場合、再送の前に操作IDで状態を確認する設計が必要です。失敗の回復が二重実行を起こさないようにします。

再試行が集中する状況を試す

一時的な制限が解除された直後、待っていた要求が一斉に再送されると、再び負荷が集中する可能性があります。待ち時間の分散、同時実行数、要求の有効期限を組み合わせ、古くなった仕事をいつまでも処理しないようにします。具体的なヘッダーや再試行の仕様は公式資料に従い、アプリ全体の再送量も観測します。各処理が単独では正しくても全体で問題になる例です。

エラー処理を評価するときは、正常な応答へ戻るまでの利用者の状態も確認します。画面が処理中のまま残る、同じ要求が複数の待ち行列へ入る、利用者の中止後も通知が送られる、といった不整合がないかを点検します。再試行に成功した回数だけでなく、最終的に一件の仕事がどう終了したかを追うことが重要です。

429という番号だけで、短い待機へ送らない

確認時点の公式資料では、429には一時的な送信量の制限だけでなく、利用枠や支出上限に関する場合も含まれます。retry-afterの有無や文書化されたエラー詳細も確認し、待てば戻るものと運用側の確認が必要なものを分けます。経路や契約による差を無視し、すべての429へ同じ再送を続ける設計にはしません。

再試行の責任をSDKとアプリの両方へ無制限に置くと、想定より多く送信することがあります。利用するSDKの設定を確認し、アプリでは一件の仕事としての期限と上限を管理します。待機の案内には再送を連打する必要がないことと、中止できる範囲を示し、期限を過ぎた要求を新しい仕事と混ぜないようにします。

HTTP成功の後と、操作結果不明の時点にも終了条件を持つ

SSEではHTTP 200の後にエラーが届く場合があります。接続できたことと、内容を最後まで受け取って確定できたことを分けて記録します。画面には途中の文字があっても、異常終了した結果を完成した履歴や次のツール入力へ渡さないようにします。具体的な完了の見方はストリーミングの記事へ進んで確認してください。

下の復旧表は設計用の期待動作で、Claude APIへ障害を起こして測定した結果ではありません。生成の再送が可能でも、すでに実行した外部更新を繰り返せるとは限りません。更新先の応答がないときは操作IDで状態を照会し、確認できないものを「未実行」と決めつけないようにします。復旧の担当と最終状態まで決めることが重要です。

具体例で考える

説明用のアプリで、入力の不備、待機可能な制限、利用枠の停止、途中のSSEエラー、更新結果不明を同じ再送ボタンにまとめてしまった状況を分けます。実サービスへの障害試験ではありません。

【復旧経路を決めるための設計表】
入力不備：内容を修正するまで同じ要求を自動再送しない。
401／403：認証・アクセス設定を運用側で確認。秘密を画面に出さない。
429＋待機可能な制限：公式ヘッダーと残り期限を確認して待機。
429＋利用枠の停止：エラー詳細を照合し運用確認へ。短い反復を続けない。
500／529：一時障害を想定し、期限・回数を限定した復旧を検討。
HTTP 200後のSSEエラー：未完了。表示できた断片を確定保存しない。
書込みの結果が不明：同じ操作IDで照会。新規操作として自動再実行しない。

記録するもの：仕事ID、要求ID、分類、開始時刻、期限、最終状態。
記録を避けるもの：APIキー、必要のない入力全文、認証ヘッダー。

再送できるかという一つの判定に、入力修正、待機、設定確認、操作結果の照会を押し込めないようにします。要求IDは診断に役立つ識別子で、業務の重複防止キーとは役割が違います。正常に復帰したかだけでなく、期限内に一件の仕事として終了したか、未完了の表示や重複操作が残っていないかも点検します。

確認課題と合格の目安

四種類の失敗について、再送の可否、確認担当、利用者への表示を表にしてください。

• 入力不備を無制限に再送しない。
• 待機と上限を設けている。
• 生成失敗と更新結果不明を区別している。