# エラーとリトライ
> エラーエンベロープ、retryable ルール、エラーコード一覧。

> 以下の表は Beatra の公開エラーコード定義から自動生成されます。

Beatra の公開エラーレスポンスはすべて、共通のエラーエンベロープを使います。`error.code` は下表の安定した公開値のいずれかで、`error.retryable` はそのまま再試行して成功する可能性があるかを示します。

エラーレスポンスの本文は次の形です。

```json
{
  "error": {
    "code": "<machine code>",
    "type": "<error family>",
    "message": "<human description>",
    "retryable": true,
    "param": "/field",
    "details": {},
    "request_id": "req_..."
  }
}
```

## どう分岐するか

| 見るもの | すること |
|---|---|
| `retryable: true` | 短いバックオフの後に**まったく同じリクエスト**と同じ `Idempotency-Key` で再試行できます。`Retry-After` ヘッダーがある場合はそれに従ってください。`429` レスポンスには `X-RateLimit-*` ヘッダーも付きます。 |
| `retryable: false` | 再試行しても同じ結果になります。リクエストを変更する、認証情報を直す、またはユーザーにエラーを表示してください。再試行できないエラーでループするのはバグです。 |
| `error.param` | ある場合は、リクエスト本文の問題のあるフィールドを指す JSON Pointer（RFC 6901）です。 |
| `error.type` / `error.details` / `error.request_id` | それぞれ安定したエラーの種類、修正に必要な情報、追跡用の識別子です。 |
| `error.message` | 診断用の文章で、分岐の条件には使えません。モデルサービスの応答後にタスクが最終的に失敗した場合は、認証情報・署名付き URL・制御文字・長さに関する安全処理を施したうえで、モデルサービス側の文言をそのまま保持します。 |

`error.details.recovery` がある場合は、トップレベルのエラーエンベロープを変えずに、分岐に使える対処を示します。`requires_input_change` は送信した内容を変更する必要があるかどうかを示します。`client_request_id: new` は、修正後の作業または終了した作業が新しい論理リクエストであることを意味します。それ以外の場合は `retryable` とエンドポイントの冪等性ルールに従ってください。

```json
{
  "details": {
    "recovery": {
      "action": "fix_arguments_and_resubmit",
      "requires_input_change": true,
      "client_request_id": "new"
    }
  }
}
```

## 認証とアカウント

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `unauthorized` | 401 | 不可 | 認証情報がないか、形式が正しくありません。`Authorization: Bearer <API key>` を送信してください。 |
| `invalid_api_key` | 401 | 不可 | API キーが無効、無効化済み、取り消し済み、または存在しません。コンソールの「開発者向け → API キー」でキーを作成またはローテーションし、新しいキーで再試行してください。 |
| `api_key_region_mismatch` | 400 | 不可 | API キーのリージョン接頭辞がこのエンドポイントと一致しません。キーのリージョンに対応する API ホストを呼び出すか、このリージョン向けに発行されたキーを使用してください。 |

**ほか 3 件**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `tenant_disabled` | 403 | 不可 | アカウントが一時停止または無効化されています。サポートにお問い合わせください。再試行しても成功しません。 |
| `forbidden` | 403 | 不可 | 呼び出し元にこの操作の権限がありません。必要な権限を持つ認証情報を使用してください。そのまま再試行しても成功しません。 |
| `email_send_failed` | 502 | 可 | ログインコードのメールを一時的に送信できませんでした。少し待ってから新しいコードをリクエストしてください。 |

## 課金

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `insufficient_balance` | 402 | 不可 | クレジットが不足しています。このリクエストは開始されておらず、課金もされていません。https://console.beatra.ai/wallet?intent=buy でクレジットを追加すると、すぐに反映されます。その後、同じリクエストを再試行してください。再インストールや再承認は不要です。 |
| `billing_failed` | 500 | 可 | 課金または返金が、再試行後も失敗しました。同じ Idempotency-Key / client_request_id で再試行してください。同じ識別子であれば二重課金は発生しません。 |
| `payment_provider_unavailable` | 503 | 不可 | この支払い方法の決済サービスが設定されていません。コンソールで別の支払い方法を選択してください。 |

## 容量と可用性

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `rate_limited` | 429 | 可 | 呼び出し元のレート制限を超えました。`Retry-After` の間隔を空けてから再試行してください。`X-RateLimit-*` ヘッダーに現在の上限が示されます。 |
| `model_unavailable` | 503 | 可 | 指定したモデルは現在利用できません。バックオフして再試行するか、選択可能な別のモデル（`beatra.models.list` または `GET /v1/catalog/models`）に切り替えるか、`model=auto` を使用してください。 |
| `model_request_failed` | 502 | 可 | 再試行可能なサービスエラーの後も、モデルへのリクエストが失敗しました。バックオフして再試行してください。続く場合は入力を調整するか、別のモデルを選んでください。 |

**ほか 4 件**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `model_timeout` | 504 | 可 | モデルへのリクエストがタイムアウトしました。バックオフして再試行してください。 |
| `model_rate_limited` | 429 | 可 | モデルの処理能力がレート制限されました。バックオフして再試行してください。 |
| `model_output_invalid` | 502 | 可 | モデルの生成は成功しましたが、生成されたファイルを何度試してもダウンロードできませんでした。タスクは失敗となり、結果ファイルはありません。 |
| `internal_error` | 500 | 可 | 分類されていないサーバー側のエラーです。同じ冪等性の識別子で再試行してください。続く場合は request_id を添えてご報告ください。 |

## その他のエラーコード

**リクエストの検証 15 件 ⌄**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `invalid_request` | 422 | 不可 | リクエスト本文が構造の検証を通過しませんでした。`param` は最初に問題のあるフィールドを指し、`details.errors` にはすべての不備とその `loc`、理由が含まれます。該当するフィールドを修正して再送信してください。 |
| `skill_package_format_invalid` | 422 | 不可 | Skill パッケージの識別子の形式が正しくありません。64 文字以内の小文字とハイフンからなる slug と、有効な SemVer のパッケージバージョンを使用してください。 |
| `unsupported_capability` | 400 | 不可 | この機能は存在しないか、無効になっています。現在利用できる機能は `GET /v1/catalog/capabilities` で確認できます。 |
| `unsupported_model` | 400 | 不可 | このモデルは存在しないか、この機能では選択できません。`beatra.models.list` または `GET /v1/catalog/models` で選択可能なモデルを確認するか、`model=auto` を使用してください。 |
| `unsupported_option` | 422 | 不可 | 選択した具体的なモデルが、リクエストされた値またはコントロールに対応していません。`param` が該当するフィールドを示し、`details.candidate_failures[]` に `unsupported_resolution`、`unsupported_duration`、`unsupported_aspect_ratio` などの具体的な失敗コードと、受け取った値・対応する値が含まれます。該当するフィールドを変更するか、別のモデルを選んでください。`model=auto` の場合は、どの候補もリクエストを満たせないときにのみ返されます。 |
| `no_eligible_model` | 422 | 不可 | `model=auto` のリクエスト全体を満たせるモデルが現在ありません。`details.candidate_failures[]` に各候補が対応できない理由が列挙されます。互換性のないフィールドだけを変更するか、一覧にある具体的なモデルを選んでください。 |
| `voice_model_incompatible` | 422 | 不可 | 指定した音声は、指定したモデルでは利用できません。`model=auto`、互換性のあるモデル、または音声一覧の別の音声を使用してください。 |
| `unsupported_input_modality` | 422 | 不可 | 選択したモデルは、リクエストに含まれる入力の種類（画像、音声、ファイルなど）に対応していません。`param` が最初に問題のあるフィールドを示します。そのフィールドを削除するか、対応するモデルを選んでください。 |
| `context_length_exceeded` | 422 | 不可 | リクエストが、選択したモデルのコンテキスト長を超えています。入力を短くするか、より長いコンテキストに対応するモデルを選んでください。 |
| `safety_rejected` | 400 | 不可 | リクエストがコンテンツの安全審査を通過しませんでした。ユーザーにプロンプトとすべての入力素材を確認してもらい、安全でない可能性のある内容を修正または差し替えたうえで、新しい client_request_id で新しいタスクとして送信してください。同じ内容で再試行しても解決しません。 |
| `content_filtered` | 502 | 不可 | 生成の途中で、安全フィルターが出力をブロックしました。プロンプトを言い換えるか、別のモデルに切り替えてください。同じ内容で再試行すると、通常は再びブロックされます。 |
| `not_found` | 404 | 不可 | リクエストされた HTTP リソースまたはエンドポイントが見つかりません。パスと識別子を確認してください。そのまま再試行しても成功しません。 |
| `streaming_not_yet_implemented` | 501 | 不可 | 旧バージョンとの互換用のコードです。以前のデプロイでは `stream=true` を認識していましたが、ストリーミングは有効になっていませんでした。 |
| `invalid_window` | 422 | 不可 | 期間の指定が無効です。 |
| `invalid_cursor` | 400 | 不可 | ページネーションのカーソルの形式が正しくありません。 |

**コールバック 3 件 ⌄**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `callback_url_required` | 422 | 不可 | コールバック署名キーを選択した場合は、コールバック URL が必要です。`callback_url` を追加するか、`callback_signing_key_id` を外してください。 |
| `callback_signing_key_not_found` | 404 | 不可 | コールバック署名キーが存在しないか、このアカウントからは参照できません。コンソールで署名キーの一覧を確認し、有効なキー ID を指定してください。 |
| `callback_signing_key_inactive` | 422 | 不可 | このコールバック署名キーは廃止済みのため、新しいタスクでは選択できません。有効なキーを選択するか、署名なしで配信する場合はキー ID を省略してください。 |

**メディア入力 5 件 ⌄**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `invalid_media` | 422 | 不可 | メディア入力の形式が正しくないか、デコードできません。ファイルを書き出し直すか再エンコードしてから、もう一度送信してください。`param` が問題のあるフィールドを示します。 |
| `unsupported_media_type` | 422 | 不可 | この機能はこのメディア形式に対応していません。対応する形式（機能ページまたはモデルの制約を参照）に変換してから再送信してください。 |
| `media_too_large` | 413 | 不可 | メディア入力がサイズの上限を超えています。入力を圧縮またはトリミングするか、先にアップロードしてアーティファクト参照を渡してください。 |
| `media_fetch_failed` | 422 | 可 | Beatra が入力リソースにアクセスできませんでした。リソースに HTTPS でアクセスできるか確認するか、アップロードしてアーティファクト参照を渡してください。 |
| `upload_stalled` | 408 | 可 | アップロードのデータ送信が長時間止まったか、アップロードの制限時間を超えました。同じアップロード URL に同じ PUT をもう一度送信してください。アップロードの許可が期限切れの場合は、`beatra.assets.upload` で新しく取得してください。 |

**タスクとリソース 11 件 ⌄**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `task_not_found` | 404 | 不可 | task_id が存在しないか、このアカウントのものではありません。作成時に返された task_id を使用してください。最近のタスクは `GET /v1/tasks` または `beatra.tasks.list` で一覧できます。 |
| `conflict` | 409 | 不可 | 操作がリソースの現在の状態と競合しています。タスクのキャンセルの場合は、実行が継続されることを意味します。`details.action` に従ってください（通常は同じタスクのポーリングを続けます）。作業を再送信しないでください。 |
| `result_undeliverable` | 502 | 不可 | 完了した結果を返せませんでした。サイズが大きすぎる、ネストが深すぎる、または有効な JSON ではありません。同じ照会を再送信しないでください。 |
| `artifact_not_found` | 404 | 不可 | artifact_id が存在しないか、このアカウントのものではありません。メディアをもう一度アップロードし、新しく返されたアーティファクト ID を使用してください。 |
| `voice_not_found` | 404 | 不可 | voice_id が存在しないか、このアカウントのものではありません。利用できる音声は `GET /v1/voices` または `beatra.voices.list` で一覧できます。 |
| `voice_activation_required` | 422 | 不可 | この音声は無料のプレビューです。音声合成に使うには有効化が必要です。先にユーザーへ有効化料金を確認してから、`beatra.voices.activate` を呼び出してください。 |
| `price_confirmation_required` | 422 | 不可 | 有効化の見積もりが期限切れか、内容が変わりました。新しい見積もりをユーザーに示して同意を得てから、新しい `confirmation_token` と `confirm_credits` で `beatra.voices.activate` を再度呼び出してください。 |
| `voice_preview_expired` | 422 | 不可 | このプレビュー音声は期限切れのため、有効化も音声合成もできません。音声をもう一度クローンしてください。 |
| `voice_sample_rejected` | 422 | 不可 | 音声サンプルは拒否されました。`details.reason` を確認し、サンプルを修正してから新しい `client_request_id` でクローンし直してください。 |
| `voice_limit_reached` | 409 | 不可 | このアカウントで有効化待ちのクローン音声が上限に達しています。1 つを有効化するか、デスクトップアプリで 1 つ削除するか、`DELETE /v1/voices/{voice_id}` で削除してください。待ちの音声は 7 日後に期限切れになります。 |
| `voice_activation_daily_limit` | 429 | 不可 | このアカウントは今日すでにクローン音声を 3 件有効化し、1 日の上限に達しました。今回は課金されていません。今日さらに有効化するには Beatra サポートにご連絡ください。上限は UTC 00:00（日本時間 09:00）にリセットされます。 |

**冪等性とレスポンスモード 2 件 ⌄**

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `idempotency_conflict` | 409 | 不可 | 同じ `Idempotency-Key` / `client_request_id` が、異なるリクエスト本文で使われました。内容を変えた作業は新しい識別子で送信し、同じ作業をそのまま再試行する場合は元の識別子を再利用してください。どちらにするか決める前に、既存のタスクを確認してください。 |
| `request_in_progress` | 409 | 可 | 同じ冪等性の識別子を持つリクエストがまだ処理中です。後で同じ識別子で再試行すると、元のレスポンスが返されます。 |

## 非同期タスクの失敗

生成リクエストが正常に受け付けられた後で、`status: failed` で終わることがあります。REST のタスク照会、MCP の `beatra.tasks.get`、コールバックは、いずれも同じ `Task.error` オブジェクト（`code`、`type`、`message`、`retryable`、任意の `param`、任意の `details`、`request_id`）を返します。失敗したタスクの照会結果はタスクの最終状態であり、MCP プロトコルのエラーではありません。

`model_output_invalid` は、モデルの生成は成功したものの、Beatra が生成ファイルを何度試してもダウンロードできなかったことを意味します。この失敗したタスクには結果ファイルがありません。

## MCP ツールのエラー

MCP ツールの呼び出しが失敗すると、`isError: true` のツール結果が返ります。`structuredContent.error` には REST のエンベロープと**同じ項目**（`code`、`type`、`message`、`retryable`、ツール引数を指す JSON Pointer の任意の `param`、任意の `details`）と、JSON-RPC の `jsonrpc_code` が入ります。REST と同様に `code` と `retryable` で分岐してください。

MCP 専用のコードは `insufficient_scope` の 1 つだけです。OAuth の付与に必要なスコープが不足しており、`missing_scopes` に不足分が示されます。Beatra のデバイス承認をやり直してください。承認し直さずに再試行しても成功しません。予期しないサーバー障害は `internal_error` のツール結果として返り、素の HTTP エラーにはなりません。

---

このページは公開ランタイムエラーコード 52 件から生成されています。内部用、管理用、またはサービス連携専用の 25 件は、公開ドキュメントには掲載していません。