# エラー

出典: https://docs.aicentos.com/ja/billing/errors

Language: ja

> HTTP ステータスコード、エラーレスポンスの構造、よくあるエラーと解決策

aicentos は **OpenAI のエラーレスポンス形式**をそのまま踏襲しています。SDK が例外を投げたときは、対応する例外を catch するだけで済みます。

## エラーレスポンスの構造

すべてのエラーレスポンスは次の形式です：

```bash
{
  "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

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**チェックリスト**：

* `Authorization` ヘッダーが `Bearer sk-xxx` 形式になっているか（空白に注意）
* コンソールから Key をコピーしたときに空白 / 改行が混入していないか
* Key が削除 / 無効化 / 期限切れになっていないか
* テスト用 Key を本番にコミットしていないか

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

チャージ → コンソールの「ウォレット管理」。[残高アラート](https://docs.aicentos.com/ja/billing/pricing#%E6%AE%8B%E9%AB%98%E3%82%A2%E3%83%A9%E3%83%BC%E3%83%88) を有効にして再発を防ぎましょう。

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

トークン作成時に「**利用可能モデル**」のホワイトリストをチェックしており、リクエストの model がそのリストに含まれていません。トークン設定を変更するか、Key を変えてください。

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

モデル ID のスペルミスか、すでに提供が終了しています。[モデルギャラリー](https://aicentos.com/pricing) で現在使用できる ID を確認してください。

### 429 — Rate limit exceeded

レスポンスヘッダーの `Retry-After` が、何秒後に再試行すべきかを示します。同時実行数とリクエスト頻度を下げれば回復します。

### 500 / 502 / 503 — サービス異常

多くは上流の変動によるものです。**自動で 2〜3 回再試行**すれば通常は成功します。5 分以上続く場合は：

* [ステータスページ](https://status.aicentos.com) を確認（あれば）
* サポートに問い合わせる

### 408 / 504 — タイムアウト

リクエストが 60s を超えても応答しないケースです。よくある原因：

* prompt が長すぎてモデルの「思考」がタイムアウトしている
* ストリーミング出力が有効になっていない（長いレスポンスでは `stream: true` を推奨）

**対処**：

* prompt を短くする
* ストリーミングを有効化：`{ "model": "...", "messages": [...], "stream": true }`
* より速いモデルへ切り替える（例：`gpt-4o` から `gpt-4o-mini` へ）

## SDK でのエラー処理例

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```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

```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 を直接使ってください**。