# エラーコード

Source: https://aiand-docs-staging.pages.dev/ja/errors/

## エラー形式

すべてのエラーは OpenAI 互換の形式で返ります:

```json
{
  "error": {
    "message": "A human-readable description of the error",
    "type": "error_type",
    "param": "field_name",
    "code": "error_code"
  }
}
```

`param` と `code` フィールドは任意で、`null` になることがあります。

唯一の例外は [`POST /v1/messages`](/ja/api/messages/#エラー) で、Anthropic の SDK や Claude Code がそのまま解釈できるよう、Anthropic のエンベロープで応答します:

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "A human-readable description of the error"
  },
  "request_id": "…"
}
```

`code` と `param` は設定されている場合に `error` 内に含まれます。モデルのコンテキストウィンドウを超えるリクエストは、メッセージが `prompt is too long` で始まり `capability_rejected: prompt_too_long` トークンを含む `400` となります。これは Claude Code の自動圧縮が検出する文言です。以下のステータスコードはどちらの形式にも適用されます。

## ステータスコード

| ステータス | タイプ | 説明 |
|--------|------|-------------|
| `400` | `invalid_request_error` | リクエスト検証に失敗 — JSON が不正、必須フィールドの欠落、パラメータ値が無効など。 |
| `401` | `authentication_error` | API キーや JWT トークンが欠落しているか無効。 |
| `402` | `billing_error` | 課金アカウントの残高が不足しています。クレジットを追加してから再試行してください。 |
| `403` | `authorization_error` | 認証情報は有効ですが、対象リソースへの権限が不足しています。 |
| `404` | `invalid_request_error` | リソースが見つかりません — 未知のルート、組織が利用できないモデル、または参照先のリソース (例: `file_id`) が存在しないか別の組織のものです。 |
| `410` | `invalid_request_error` | リソースが消滅 — 参照されたファイルが `expires_at` を過ぎているか、エンドポイントが廃止されたケース。 |
| `429` | `rate_limit_error` | レート制限を超過。再試行の方法はバケットによって異なります — [レート制限](/ja/reference/rate-limits/#429-レスポンス) を参照。 |
| `499` | `client_closed_request` | レスポンス完了前にクライアントが切断しました。中断されたストリームで返されます。 |
| `500` | `server_error` | リクエスト処理中に予期せぬエラーが発生しました。 |
| `502` | `server_error` | モデル推論レイヤへの到達に失敗。 |
| `504` | `server_error` | モデルがリクエストタイムアウト内に応答しませんでした。 |

`500`、`502`、`504` はいずれも `type` が `"server_error"` です。区別するには `code` を参照してください。`500` には `code` がありません。

## 主なエラーコード

`code` フィールドは `type` よりも具体的な原因を示します。代表的なもの:

| コード | ステータス | 発生条件 |
|------|--------|------|
| `invalid_value` | 400 | リクエストフィールドの値が不正 — mime タイプや purpose が不正、`image_url` / `video_url` / `file_id` に必要な capability を選択したモデルが持たない、モデルが対応していないコンテンツパートの種類、対応するツール呼び出しのないツール結果、`tools` にないツールを指定する `tool_choice`、またはモデルのコンテキスト長以上の `max_tokens`（チャットリクエストで `max_completion_tokens` を指定した場合はそのフィールド、`/v1/responses` では `max_output_tokens`）。`param` に該当フィールド名が入ります |
| `invalid_media_url` | 400 | メディア URL が [URL の要件](/ja/capabilities/vision/#url-の要件) を満たしていない。例: `http` の URL、IP アドレス、内部ホスト名。公開 `https` URL、`file_id`、base64 の `data:` URL のいずれかを使ってください。`param` に該当フィールド名が入ります |
| `context_length_exceeded` | 400 | リクエストがモデルの最大コンテキスト長を超過。プロンプトを短くするか、出力トークン数の指定を減らしてください |
| `unsupported_value` | 400 | 利用できない機能をリクエストが使っている。`/v1/responses` での `previous_response_id` や `item_reference` 入力アイテム（レスポンスオブジェクトは保存されません）、またはモデルがサポートしていない入力アイテムの種類やツールの種類。`param` に該当フィールド名が入り、標準的な種類であればメッセージにその名前が含まれます |
| `file_not_found` | 404 | 指定された `file_id` が存在しないか、組織に紐づいていない |
| `file_expired` | 410 | 指定された `file_id` が `expires_at` を過ぎている |
| `endpoint_removed` | 410 | `/v1/completions` など、廃止されたエンドポイントへのリクエスト。メッセージに代わりのエンドポイントが示されます |
| `model_not_found` | 404 | `model` が正確なモデル `id` ではない、またはモデルに組織の請求通貨での価格が設定されていない。チャットモデルは `GET /v1/models`、動画モデルは `GET /v1/videos/models` で確認できます |
| `model_deprecated` | 404 | モデルは提供を終了した。代わりに使うモデルをメッセージで案内する |
| `model_access_denied` | 404 | モデルは存在するが、組織にそのモデルの利用権限がない。利用を希望する場合は support@aiand.com までお問い合わせください |
| `invalid_api_key` | 401 | API キーが欠落、形式不正、または未知 |
| `rate_limit_exceeded` | 429 | レート制限を超過。モデルバケットによる拒否では `X-RateLimit-Policy`、認証スロットルでは `Retry-After` のみが付く |
| `insufficient_credits` | 402 | 残高不足 |
| `upstream_error` | 502 | モデル推論レイヤに到達できない、または応答を読み取れない |
| `timeout` | 504 | モデルがリクエストタイムアウト内に応答しなかった |
| `client_closed_request` | 499 | レスポンス完了前にクライアントが切断した |

## reasoning をオフにする

モデルが reasoning をオフにできるのは、公開しているレベルに `none` が含まれる場合だけです。`none` を公開していない推論モデルへ `reasoning_effort` の `none`、`reasoning.effort` の `none`、または `/v1/messages` の `thinking` ブロックで `type` `disabled` を送ると、`400` `invalid_request_error` になります。

```text
Model '<name>' cannot disable reasoning: suppressing it needs reasoning_effort 'none', which this model does not publish. Supported values: <levels>. Use '<level>' for the least reasoning.
```

`<level>` は、そのモデルが公開しているレベルのうち最も低いものです。`reasoning` 機能を持たないモデルは、これらのフィールドを無視します。

## その他の reasoning レベルのエラー

`none` 以外でモデルの一覧にないレベルは、失敗せず一つ上のレベル(なければ最も高いレベル)で実行されます。一覧にない `none` は上記の 400 になります。`ultra` のように effort の語彙にない値は `Model '<name>' does not support <field> '<value>'. Supported values: <levels>.` になります。レベルを一つも持たない推論モデルは、どのレベルにも `Model '<name>' lists no reasoning levels, so it cannot apply <field>.` を返します。

## エラーハンドリング

```python
from openai import OpenAI, APIError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiand.com/v1",
)

try:
    response = client.chat.completions.create(
        model="google/gemma-4-31b-it",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")
```

OpenAI SDK はエラーレスポンスを自動的にパースし、型付きの例外を送出します。`X-RateLimit-Policy` が付く `429` エラーでは、バケットに応じて対処してください — 時間ベースの拒否では (`Retry-After` に従って) バックオフし、concurrency の拒否では再試行せず実行中リクエストを消化させます。認証スロットルには policy が付かないため、`Retry-After` に従ってください。[レート制限](/ja/reference/rate-limits/#429-レスポンス) を参照。