> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API エラー

`Cartesia-Version: 2026-03-01` 以降では、Cartesia は構造化された JSON エラーオブジェクトを返します。

それより古い API バージョンでは、エラーがプレーンテキスト（例: `Title: Message`）になる場合があります。

## HTTP エラーオブジェクト

```json HTTP error response theme={null}
{
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

| フィールド        | 型               | 必須  | Null 可 | 備考                                        |
| ------------ | --------------- | --- | ------ | ----------------------------------------- |
| `error_code` | `string`        | はい  | はい     | マシン可読なコード。該当するコードがない場合は `null` になります。     |
| `title`      | `string`        | はい  | いいえ    | 短い人間可読のエラー要約。                             |
| `message`    | `string`        | はい  | いいえ    | 詳細な人間可読のエラー説明。                            |
| `request_id` | `string` (UUID) | はい  | いいえ    | サポート／デバッグ用のリクエスト識別子。                      |
| `doc_url`    | `string`        | いいえ | いいえ    | エラーに関するドキュメントへのオプションのリンク。利用できない場合は省略されます。 |

## WebSocket エラーイベントオブジェクト

```json WebSocket error event theme={null}
{
  "type": "error",
  "done": true,
  "status_code": 429,
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000:happy-monkeys-fly:8a0f5f3a-3b2f-4f28-b73e-8c5f27e2f8bb",
  "context_id": "happy-monkeys-fly"
}
```

| フィールド         | 型         | 必須  | Null 可 | 備考                                                                  |
| ------------- | --------- | --- | ------ | ------------------------------------------------------------------- |
| `type`        | `string`  | はい  | いいえ    | 常に `"error"`。                                                       |
| `done`        | `boolean` | はい  | いいえ    | エラーイベントでは現在常に `true`。                                               |
| `status_code` | `integer` | はい  | いいえ    | エラーに対する HTTP ライクなステータスコード。                                          |
| `error_code`  | `string`  | はい  | はい     | マシン可読なコード。`null` の場合があります。                                          |
| `title`       | `string`  | はい  | いいえ    | 短い人間可読のエラー要約。                                                       |
| `message`     | `string`  | はい  | いいえ    | 詳細な人間可読のエラー説明。                                                      |
| `request_id`  | `string`  | はい  | いいえ    | サポート／デバッグ用のリクエスト識別子。WebSocket では UUID またはメッセージごとの派生 ID 文字列の場合があります。 |
| `doc_url`     | `string`  | いいえ | いいえ    | エラーに関するドキュメントへのオプションのリンク。利用できない場合は省略されます。                           |
| `context_id`  | `string`  | いいえ | いいえ    | TTS コンテキスト識別子。利用可能な場合に存在します。                                        |

## SSE エラーイベントオブジェクト

SSE エラーは `event: error` と `data:` 行内の JSON で送信されます。

```text SSE error event theme={null}
event: error
data: {"type":"error","done":true,"status_code":500,"error_code":null,"title":"Unexpected error","message":"An unexpected error occurred, please contact support@cartesia.ai if the problem persists.","request_id":"550e8400-e29b-41d4-a716-446655440000"}
```

| フィールド         | 型               | 必須  | Null 可 | 備考                                        |
| ------------- | --------------- | --- | ------ | ----------------------------------------- |
| `type`        | `string`        | はい  | いいえ    | 常に `"error"`。                             |
| `done`        | `boolean`       | はい  | いいえ    | エラーイベントでは現在常に `true`。                     |
| `status_code` | `integer`       | はい  | いいえ    | エラーに対する HTTP ライクなステータスコード。                |
| `error_code`  | `string`        | はい  | はい     | マシン可読なコード。`null` の場合があります。                |
| `title`       | `string`        | はい  | いいえ    | 短い人間可読のエラー要約。                             |
| `message`     | `string`        | はい  | いいえ    | 詳細な人間可読のエラー説明。                            |
| `request_id`  | `string` (UUID) | はい  | いいえ    | サポート／デバッグ用のリクエスト識別子。                      |
| `doc_url`     | `string`        | いいえ | いいえ    | エラーに関するドキュメントへのオプションのリンク。利用できない場合は省略されます。 |

## 現在のエラーコード

<Note>
  将来、より多くのエラーコードが追加される可能性があります。インテグレーションは未知の
  `error_code` 値を適切に処理する必要があります。
</Note>

| `error_code`               | 意味                                    |
| -------------------------- | ------------------------------------- |
| `quota_exceeded`           | アカウントがクォータ（クレジットやエージェント使用量など）を超過しました。 |
| `concurrency_limited`      | アカウントがプランの同時実行制限を超過しました。              |
| `voice_model_mismatch`     | 要求されたボイスが、要求されたモデルと互換性がありません。         |
| `voice_not_found`          | 要求されたボイスが存在しません。                      |
| `model_not_found`          | 要求されたモデルが存在しません。                      |
| `language_not_supported`   | 要求された言語が、要求されたモデルまたはボイスでサポートされていません。  |
| `file_too_large`           | アップロードされたファイルが大きすぎます。                 |
| `unsupported_audio_format` | 指定された音声フォーマットはサポートされていません。            |
| `plan_upgrade_required`    | この機能には上位プランが必要です。                     |