レッスン 3/4 · 8 分

リクエストが失敗したとき

エラーコードとステータスで分岐し、後で成功する可能性のあるエラーだけを再試行します。

Phaseo のエラーは、どのエンドポイントでも同じ JSON 本文を返します。error オブジェクトは、OpenAI 互換の SDK がすでに読み取れる形です。

{
  "error": {
    "code": "insufficient_funds",
    "message": "...",
    "type": "insufficient_quota",
    "param": null
  },
  "generation_id": "G-...",
  "status_code": 402
}

分岐には error.code と HTTP ステータスを使い、メッセージの文言は使わないでください。generation_id は必ずログに記録します。

ステータスよくあるコード対処
400validation_error、model_requiredリクエストを修正します。error.param が対象のフィールドを示します。
401unauthorisedキーと Authorization ヘッダーを確認します。
402insufficient_fundsクレジットを追加するか、phaseo/free を使います。
403guardrail_blockedリクエストかガードレールを変更します。
404not_foundパスと ID を確認します。
410model_retiredreplacement_model に切り替えます。
429rate_limit_exceeded、key_limit_exceededRetry-After の分だけ待ってから再試行します。
5xxupstream_error、gateway_errorバックオフ付きで再試行します。

429 以外の 4xx エラーは、そのまま再試行しないでください。また失敗します。429 の場合は Retry-After(秒数または HTTP の日付)の分だけ待つか、ジッター付きの指数バックオフを使います。Retry-After のない key_limit_exceeded は自然には解除されないので、再試行しないでください。5xx は、呼び出しを繰り返しても安全な場合にだけ再試行し、試行回数の上限と全体の期限を設定します。

理解度チェック

リクエストが 401、コード unauthorised を返しました。コードはどうすべきですか?

実践してみる

バッチスクリプトがループで 500 件のリクエストを送ります。途中から、レスポンスが Retry-After: 20 ヘッダー付きの 429 で返ってくるようになりました。何を変えますか?

答えを表示

スクリプトが Retry-After に従うようにします。再試行の前に約 20 秒待ち、ヘッダーがない場合はジッター付きの指数バックオフを使います。error.code も確認してください。rate_limit_exceeded は解除されますが、Retry-After のない key_limit_exceeded は解除されないので、再試行しても意味がありません。

ポイント

error.code とステータスで分岐し、4xx エラーは修正し、再試行は 429 と安全な 5xx エラーだけにバックオフ付きで行います。

関連リンク

進捗はこのブラウザーに保存されます。

最終確認日:2026年11月17日