aicentos課金と管理
エラー
HTTP ステータスコード、エラーレスポンスの構造、よくあるエラーと解決策
最終更新:
aicentos は OpenAI のエラーレスポンス形式をそのまま踏襲しています。SDK が例外を投げたときは、対応する例外を catch するだけで済みます。
エラーレスポンスの構造
すべてのエラーレスポンスは次の形式です：
{
"error": {
"message": "あなたの API Key には gpt-5 へのアクセス権がありません",
"type": "permission_denied",
"code": "model_not_allowed",
"param": "model"
}
}| フィールド | 意味 |
|---|---|
message | 人間が読めるエラーの説明 |
type | エラーのカテゴリー（下表を参照） |
code | 細かい粒度のエラーコード（プログラムでの判定用） |
param | 問題のあるフィールド名（あれば） |
HTTP ステータスコード早見表
| ステータスコード | タイプ | よくある原因 |
|---|---|---|
400 | invalid_request_error | リクエストボディの形式エラー、不正なパラメーター、model 名のスペルミス |
401 | authentication_error | API Key の欠落 / 誤り / 失効済み |
402 | insufficient_quota | 残高不足 |
403 | permission_denied | Key が無効化されている、モデルが未許可、IP がホワイトリスト外 |
404 | not_found | エンドポイントのパス誤り、モデル ID の誤り |
408 | request_timeout | 上流のタイムアウト（通常は 60s を超えても応答なし） |
413 | payload_too_large | リクエストボディが大きすぎる（画像・ファイル） |
415 | unsupported_media_type | Content-Type が不正 |
422 | invalid_request_error | リクエストボディは解析できるが意味が不正 |
429 | rate_limit_exceeded | レート制限に抵触。リクエスト頻度を下げて再試行 |
500 | server_error | プラットフォーム内部エラー（まれ） |
502 | bad_gateway | 上流サービスの異常 |
503 | service_unavailable | 上流が過負荷。少し待ってから再試行を推奨 |
504 | gateway_timeout | 上流の応答タイムアウト |
よくあるエラーと対処
401 — Invalid API key
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }チェックリスト：
AuthorizationヘッダーがBearer sk-xxx形式になっているか（空白に注意）- コンソールから Key をコピーしたときに空白 / 改行が混入していないか
- Key が削除 / 無効化 / 期限切れになっていないか
- テスト用 Key を本番にコミットしていないか
402 — Insufficient quota
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }チャージ → コンソールの「ウォレット管理」。残高アラート を有効にして再発を防ぎましょう。
403 — Model not allowed
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }トークン作成時に「利用可能モデル」のホワイトリストをチェックしており、リクエストの model がそのリストに含まれていません。トークン設定を変更するか、Key を変えてください。
404 — Model not found
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }モデル ID のスペルミスか、すでに提供が終了しています。モデルギャラリー で現在使用できる ID を確認してください。
429 — Rate limit exceeded
レスポンスヘッダーの Retry-After が、何秒後に再試行すべきかを示します。同時実行数とリクエスト頻度を下げれば回復します。
500 / 502 / 503 — サービス異常
多くは上流の変動によるものです。自動で 2〜3 回再試行すれば通常は成功します。5 分以上続く場合は：
- ステータスページ を確認（あれば）
- サポートに問い合わせる
408 / 504 — タイムアウト
リクエストが 60s を超えても応答しないケースです。よくある原因：
- prompt が長すぎてモデルの「思考」がタイムアウトしている
- ストリーミング出力が有効になっていない（長いレスポンスでは
stream: trueを推奨）
対処：
- prompt を短くする
- ストリーミングを有効化：
{ "model": "...", "messages": [...], "stream": true } - より速いモデルへ切り替える（例：
gpt-4oからgpt-4o-miniへ）
SDK でのエラー処理例
export AICENTOS_API_KEY="sk-your-aicentos-api-key"Python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError
client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")
try:
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "hi"}],
)
except AuthenticationError:
print("キーが間違っています")
except RateLimitError as e:
print(f"レート制限中。{e.response.headers.get('Retry-After')}s 後に再試行")
except APIError as e:
print(f"その他の API エラー：{e.status_code} {e.message}")Node.js
import OpenAI, { APIError } from 'openai';
const client = new OpenAI({
apiKey: process.env.AICENTOS_API_KEY,
baseURL: 'https://aicentos.com/v1',
});
try {
const resp = await client.chat.completions.create({ ... });
} catch (err) {
if (err instanceof APIError) {
console.log(err.status, err.code, err.message);
}
}再試行とフォールバックの推奨
| エラータイプ | 推奨される対処 |
|---|---|
400 / 401 / 402 / 403 / 404 | 再試行しない。コード / 設定の誤りなので、まず切り分ける |
429 | Retry-After に従って再試行。指数バックオフ |
500 / 502 / 503 / 504 / 408 | ただちに 1〜3 回再試行。間隔は 1〜5s |
OpenAI 公式 SDK にはデフォルトで妥当な再試行ポリシーが備わっています。本番コードでは独自に fetch せず、SDK を直接使ってください。