GPT-6 Astra APIエラー：よくある15の問題とその修正方法

APIインシデントを悪化させる最速の方法は、すべてのエラーをリトライすることです。不正なスキーマはバックオフで修復されず、枯渇したクレジット残高はワーカーがさらに10回試行しても回復しません。HTTPステータス、SDKクラス、error.type、特にerror.codeでエラーを診断してください。

安全なエラーハンドラ

try {
  return await client.responses.create({
    model: "gpt-6-astra",
    入力
  });
} エラーをキャッチ {
  if (error instanceof OpenAI.APIConnectionError) {
    // Network, proxy, TLS, DNS or firewall path.
  } else if (error instanceof OpenAI.RateLimitError) {
    // Inspect code and Retry-After before deciding to retry.
  } else if (error instanceof OpenAI.APIError) {
    console.error(error.status, error.message, error.code);
  } else {
    エラーをスローする;
  }
}

リクエストID、タイムスタンプとタイムゾーン、モデル、エンドポイント、ステータス、コード、リトライ回数、およびサニタイズされたペイロード特性をログに記録します。デフォルトでは、APIキーや機密性の高いプロンプトの内容をログに記録しないでください。

1. 400 不正なリクエスト

ペイロードの形式が不正であるか、互換性がありません：誤ったフィールド、入力の欠落、無効なツールスキーマ、サポートされていない組み合わせ、またはエンコードが不適切なコンテンツ。メッセージを読み、現在のResponsesリファレンスと比較し、契約テストを追加してください。変更されていない入力を再試行しないでください。

2. 401 認証エラー

キーまたはトークンが無効、期限切れ、失効、または誤って送信されています。シークレットの注入とプロジェクト環境を確認してください。露出したキーはローテーションし、デバッグ中に出力しないでください。

3. 401 不正な組織またはプロジェクト

有効なキーでも、間違ったスコープを対象とする可能性があります。プロジェクト設定と、明示的な組織/プロジェクトヘッダーを確認してください。キー、リソース、および請求スコープを一致させてください。

4. 401 IPが許可されていません

リクエストの発信元が設定された許可リストと一致しません。承認された出口IPから送信するか、許可された管理者を通じて許可リストを更新してください。同じ発信元から再試行しても効果はありません。

5. 403 アクセス権限がない、またはサポートされていないリージョン

発信者はリソース、モデル、またはリージョンへのアクセス権限がありません。プロジェクトのロール、モデルの利用可能性、リソースの所有権、および対応国ルールを確認してください。内部ログで権限の問題を「見つかりません」と偽装しないでください。

6. 404 見つかりません

、会話、ベクトルストア、ファイル、またはその他の識別子が間違っているか、期限切れか、アクセスできません。正確なIDとプロジェクトを確認してください。ユーザー向けの場合は、そのユーザーの範囲外のリソースの存在を漏らさないようにしてください。

7. 409 コンフリクト

別のリクエストが同時にリソースを変更しました。現在の状態を再読み込みし、新しいバージョンに対して意図した変更を再適用し、楽観的ロックまたは冪等性を使用してください。盲目的な即時再試行は競合を繰り返す可能性があります。

8. 422 処理不能エンティティ

構文としては受け入れ可能ですが、サービスで処理できません。サイズ、エンコーディング、ファイルの状態、フィールドの組み合わせを検証してください。公式テーブルでは再試行が推奨されていますが、まずは確定的な原因を取り除いてください。

9. 429 リクエストまたはトークンレート制限

トラフィックのペースを調整し、Retry-Afterが存在する場合はそれに従ってください。それ以外の場合は、ジッターを伴う上限付き指数バックオフを使用してください。ワーカー間で再試行予算を調整し、サンダリング・ハード（雪崩的アクセス）を引き起こさないようにしてください。冗長な呼び出しや大量のトークン急増を減らしてください。

10. 429 slow_down

これはランプレート信号です：ヘッドライン制限が十分に見えても、トラフィックが急増しすぎました。Retry-Afterに従い、リクエストレートを減らし、その後徐々に増やしてください。OpenAIの現在のガイダンスでは、1分あたり100万入力トークンに達した後は、15分ごとに50%以上の成長を避けるべきという経験則が示されています。実際の作動はモデルや条件によって異なります。

11. 429 クレジット、利用額、または使用制限

コードには credit_balance_exhausted、organization_spend_limit_exceeded、project_spend_limit_exceeded、organization_usage_limit_exceeded が含まれます。これらはクレジットまたは制限の変更が必要です。再試行してもアクセスは復元されません。所有者に警告し、迅速に失敗してください。

12. 500 内部サーバーエラー

しばらく待ってから制限付きの予算で再試行し、失敗が続く場合はステータスページを確認してください。サポート用にリクエストIDを記録してください。状態を変更するワークフローの場合は、リクエスト全体を再実行する前にツールの副作用を調整してください。

13. 503 モデル過負荷

ドキュメントに記載されているタイプ/コードは service_unavailable_error / server_is_overloaded です。Retry-After を尊重するか、存在しない場合はバックオフしてください。現在のPython SDKガイダンスでは、429の RateLimitError と503の InternalServerError を区別していることに注意してください。以前の過負荷ロジックですべての容量問題が429であると想定していた場合は、両方をキャッチしてください。

14. 接続またはタイムアウトエラー

APIConnectionErrorはネットワーク、プロキシ、TLS証明書、DNS、またはファイアウォールの問題を示す可能性があります。APITimeoutErrorは期限が切れたことを意味します。安全な読み取りを再試行し、企業のプロキシ設定を確認し、TLS検証を無効にしないでください。書き込みの場合は、再試行する前に操作が実行されたかどうかを判断してください。

15. WebSocketの状態とストリーミング障害

previous_response_not_foundは、参照された状態を解決できないことを意味します。公式ガイダンスでは、previous_response_idをnullに設定して完全な入力コンテキストを再送信するよう指示されています。websocket_connection_limit_reachedは60分の接続制限を示しており、新しい接続を開いて続行します。また、ソケットのクローズが完了を意味すると想定するのではなく、response.failed、response.incomplete、およびトランスポートのerrorイベントを処理してください。

リトライマトリックス

| クラス | リトライ未変更？ | 正しいアクション | | 400/401/403/404 | いいえ | リクエスト、ID、権限、またはIDを修正してください | | 409 | 調整後 | バージョンを再読み込みして安全に適用 | | 422 | 時々 | まず決定論的原因を確認してください | | 429 レート/スローダウン | はい、制限あり | Retry-After を尊重；バックオフとジッター | | 429 課金/制限 | いいえ | クレジットを追加するか、承認された制限を変更してください | | 500/503 | はい、制限あり | バックオフ、ステータス確認、リクエストID保持 | | 接続/タイムアウト | 依存 | 読み取りの再試行、書き込みの調整 |

キャップ試行回数と総経過リトライ時間。広範囲なインシデント時にはサーキットブレーカーを使用し、オペレーターの確認が必要なジョブにはデッドレターパスを利用します。リトライは観測可能であるべきで、積み重なったSDKやアプリケーションのループ内に隠れてはいけません。

よくある質問

429エラーが出た場合、毎回リトライすべきですか？

いいえ。レートおよびランプエラーは必要な遅延後に再試行できますが、クレジット、支出、使用量制限のエラーはアカウントの対応が必要です。

リクエストIDを記録する理由は？

サポートや自社のテレメトリが、完全なペイロードを公開することなく、特定のAPIリクエストと障害を関連付けることができます。

タイムアウトしたツール呼び出しを再試行できますか？

副作用を引き起こしたかどうかを確認した後にのみ行ってください。冪等性キーと再試行前の読み取りによる調整を使用してください。

ユーザーは何を見るべきですか？

簡潔で実行可能なメッセージと、適切な場合の安全な再試行オプション。スタックトレース、プロバイダコード、機密詳細は保護された診断情報に保持します。

結論

信頼性の高いGPT-6 Astraエラーハンドリングは分類から始まります。決定論的な4xxリクエストを修正し、レート制限と課金制限を区別し、一時的な5xx障害からはバックオフし、不確実な書き込みを調整し、ストリーミングをステートマシンとしてモデル化します。バウンドされたリトライポリシーと適切なリクエストレベルのテレメトリを組み合わせることで、無差別なリトライよりも多くのインシデントを解決できます。