大規模モデル API 共通 HTTP ステータス コード (401/402/403/429/529) クイック トラブルシューティング マニュアル
OpenAI、Anthropic Claude、および Gemini インターフェイスを呼び出すときの一般的な HTTP ステータス コードの意味、位置決め方法、およびクライアントの再試行のベスト プラクティスの包括的な概要。
ステータスコードクイックチェックリスト
| HTTPステータスコード | エラーの分類 | 主な理由 | 推奨されるソリューション |
|---|
| 400 Bad Request |リクエスト形式エラー | JSON フィールドが不正であるか、max_tokens が上限を超えているか、プロトコルが間違って選択されています。エンドポイント プロトコルを確認します (たとえば、クロードのネイティブ パラメーターが /v1/messages に送信されます)。
401 Unauthorized | ID 認証に失敗しました | sk-... キーのスペルが間違っているか、無効になっているか、リクエスト ヘッダーが欠落しています。 [ログイン不要のキー生存性テスト] (/check) へ ワンクリックでキーの有効性を検証 |
|---|
| 402 / 403 Forbidden |クォータまたは権限が制限されている |アカウント残高が不十分、サブキー クォータが枯渇している、IP がホワイトリストに含まれていない、またはグループにモデルが含まれていません。コンソールのバランス、サブキー クォータの進行状況バー、バインディング グループを確認します。
| 429 Too Many Requests |レートまたは同時電流制限 |アカウント内の同時チャネルの最大数を超えるか、サブキーの 5 時間/日のローリング制限をトリガーします。クライアントで指数バックオフ再試行を有効にするか、コンソールでレート制限ポリシーを増やします。
| 502 / 503 / 529 |上りの瞬間的な輻輳 |公式アップストリーム コンピューティング パワーのピーク期間中の瞬間的なジッター |ゲートウェイにはミリ秒レベルの自動災害復旧スイッチングが組み込まれており、クライアントは再試行することで復旧できます。
コンソールで特定のエラーの詳細を表示するにはどうすればよいですか?
開発者コンソールにログインした後、左側のメニュー 「📜 通話料金 → 異常リクエストのトラブルシューティング」 をクリックすると、盲目的に推測することなく、タイムスタンプ、ターゲット モデル、HTTP ステータス コード、および最近の 200 件以外のリクエストの特定のエラー概要を直接表示できます。
運用環境 SDK 指数バックオフ再試行コードの例
from openai import OpenAI
# 官方 SDK 默认自带 max_retries=2 指数退避,生产环境建议设为 3
client = OpenAI(
base_url="https://suptoken.ai/v1",
api_key="sk-your-key",
max_retries=3,
timeout=120.0,
)
🚀 准备好在项目中极速接入了吗?
注册即可创建专属 API Key,原生直连 Claude 4.5、GPT-5 Codex 与 Gemini 2.5 Pro。