リクエストが失敗したとき
エラーコードとステータスで分岐し、後で成功する可能性のあるエラーだけを再試行します。
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 は必ずログに記録します。
| ステータス | よくあるコード | 対処 |
|---|---|---|
400 | validation_error、model_required | リクエストを修正します。error.param が対象のフィールドを示します。 |
401 | unauthorised | キーと Authorization ヘッダーを確認します。 |
402 | insufficient_funds | クレジットを追加するか、phaseo/free を使います。 |
403 | guardrail_blocked | リクエストかガードレールを変更します。 |
404 | not_found | パスと ID を確認します。 |
410 | model_retired | replacement_model に切り替えます。 |
429 | rate_limit_exceeded、key_limit_exceeded | Retry-After の分だけ待ってから再試行します。 |
5xx | upstream_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日