# Beatra のトラブル対処：ログイン・クレジット・エラー
> ログイン、クレジット不足、遅いタスク、パラメーター、バージョン、見つからないリソースの 6 つの問題と、すべてのエラーコードの対処。

Beatra の失敗には、必ずエラーコード `code` と再試行の可否 `retryable` が付きます。REST のエラーレスポンス、失敗した MCP ツールの結果、失敗したタスクのいずれにも含まれます。下の症状から当てはまるものを選び、手順を順に試してください。各セクションの最後に、その症状に属するエラーコードと、それぞれの対処を載せています。エラーレスポンスの構造と再試行のルールは[エラーとリトライ](https://docs.beatra.cn/ja/docs/mechanisms/errors)にあります。

## ログインできない [#sign-in]

Agent が Beatra にログインするのは、ブラウザでの一度だけです。Beatra Skill がデバイスコードを申請し、承認ページを開いて、あなたの承認を待ちます。Skill フォルダー内のログイン補助スクリプト `scripts/authorize.py` は、接続が使える状態になると `Beatra is ready` と出力します。

1. **`BEATRA_AUTH_PENDING` と出力された。** 承認はまだ完了していません。表示された承認リンクを開いてログインし、「接続を許可」を選んでから、Agent に同じコマンドをもう一度実行させてください。何度実行しても同じ承認の続きになるため、承認は一度で済みます。承認ページは最長 1 時間有効です。
2. **`access_denied` または `expired_token` と出力された。** 承認が拒否されたか、「接続を許可」を選ぶ前にページの期限が切れました。Agent に `python3 scripts/authorize.py` をもう一度実行させ、新しい承認ページを開いてください。
3. **以前は使えたのに `BEATRA_AUTH_REQUIRED` と表示される。** このパソコンのログインが終了しています。15 日間使われなかったか、[コンソール](https://console.beatra.cn/agents)の「デバイス」でこのパソコンの接続が解除されました。Agent に `python3 scripts/authorize.py` をもう一度実行させ、一度承認してください。
4. **ツールの呼び出しが `insufficient_scope` を返す。** 接続に、ツールが必要とする権限が足りません。足りない権限は `missing_scopes` に表示されます。`python3 scripts/authorize.py --force` で接続し直し、一度承認してください。接続し直さずに再試行しても、同じエラーになります。
5. **ログインページが開かない、または認証コードが届かない。** [ログインのトラブルシューティング](https://docs.beatra.cn/ja/docs/sign-in-help)で、WeChat の QR コード、メールと SMS の認証コード、別のアカウントにログインしてしまった場合の手順を説明しています。
6. **自作のアプリケーションが `401` を受け取る。** コンソールの「開発者向け → API キー」で作成したキーを `Authorization: Bearer <API key>` で送り、キーのリージョンに対応する API ホストを呼び出してください。[認証とリクエスト規約](https://docs.beatra.cn/ja/docs/authentication)を参照してください。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `unauthorized` | 401 | 不可 | 認証情報がないか、形式が正しくありません。`Authorization: Bearer <API key>` を送信してください。 |
| `invalid_api_key` | 401 | 不可 | API キーが無効、無効化済み、取り消し済み、または存在しません。コンソールの「開発者向け → API キー」でキーを作成またはローテーションし、新しいキーで再試行してください。 |
| `api_key_region_mismatch` | 400 | 不可 | API キーのリージョン接頭辞がこのエンドポイントと一致しません。キーのリージョンに対応する API ホストを呼び出すか、このリージョン向けに発行されたキーを使用してください。 |
| `tenant_disabled` | 403 | 不可 | アカウントが一時停止または無効化されています。サポートにお問い合わせください。再試行しても成功しません。 |
| `forbidden` | 403 | 不可 | 呼び出し元にこの操作の権限がありません。必要な権限を持つ認証情報を使用してください。そのまま再試行しても成功しません。 |
| `email_send_failed` | 502 | 可 | ログインコードのメールを一時的に送信できませんでした。少し待ってから新しいコードをリクエストしてください。 |

## クレジットが足りない [#credits]

有料のツールは、開始前に残高を確認します。足りない場合は `insufficient_balance`（HTTP 402）が返ります。このときタスクは開始されず、課金もされていません。

1. **コンソールでチャージする**：[console.beatra.cn/wallet](https://console.beatra.cn/wallet?intent=buy)。クレジットはすぐに反映されます。ウォレットの「チャージ先：…」の行に、クレジットが入るアカウントが表示されます。
2. **同じリクエストをそのまま再試行する**：引数も `client_request_id` または `Idempotency-Key` も変えません。再インストールや再ログインは不要です。
3. **Agent を使っている場合は、チャージしたことを伝える。** 一度拒否されると、Beatra Skill はこのパソコンで同じツールへの以降の呼び出しに同じメッセージ（`details.local_hold`）を返し、チャージ済みと伝えるまで送信しません。そのため、まとめて実行している作業は最初に拒否された時点で止まります。この保留は 30 分後に自動で解除されます。
4. **チャージできたのに残高が変わらない。** クレジットが別のアカウントに入った可能性が高いです。Agent から受け取ったチャージ用リンクをもう一度開いて「チャージ先：…」を確認するか、2 つのアカウントを統合してください。[アカウントと統合](https://docs.beatra.cn/ja/docs/accounts#merge)を参照してください。
5. **タスクの後で残高がマイナスになった。** タスクの実際の使用量が見積もりを超えることがあります。成果物はそのまま有効です。新しい有料の作業はチャージ後に行えます。

モデルごとのクレジット価格は `beatra.models.list` と `GET /v1/catalog/models` の最新データで確認できます。プランと追加パックは[料金ページ](https://www.beatra.cn/ja/pricing)にあります。課金と返金の仕組みは[課金と使用量](https://docs.beatra.cn/ja/docs/mechanisms/billing)をご覧ください。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `insufficient_balance` | 402 | 不可 | クレジットが不足しています。このリクエストは開始されておらず、課金もされていません。https://console.beatra.cn/wallet?intent=buy でクレジットを追加すると、すぐに反映されます。その後、同じリクエストを再試行してください。再インストールや再承認は不要です。 |
| `billing_failed` | 500 | 可 | 課金または返金が、再試行後も失敗しました。同じ Idempotency-Key / client_request_id で再試行してください。同じ識別子であれば二重課金は発生しません。 |
| `payment_provider_unavailable` | 503 | 不可 | この支払い方法の決済サービスが設定されていません。コンソールで別の支払い方法を選択してください。 |
| `voice_activation_required` | 422 | 不可 | このボイスは無料のプレビューです。音声合成に使うには有効化が必要です。先にユーザーへ有効化料金を確認してから、`beatra.voices.activate` を呼び出してください。 |
| `price_confirmation_required` | 422 | 不可 | 有効化の見積もりが期限切れか、内容が変わりました。新しい見積もりをユーザーに示して同意を得てから、新しい `confirmation_token` と `confirm_credits` で `beatra.voices.activate` を再度呼び出してください。 |

## タスクが遅い・タイムアウトする [#timeouts]

生成は非同期タスクとして実行され、`queued`（待機中）、`running`（生成中）を経て、`succeeded`、`failed`、`canceled` のいずれかで終わります。`queued` または `running` のタスクは処理中で、最終状態になると結果が返ります。

1. **タスクがまだ `queued` または `running`。** 同じタスクを `beatra.tasks.get` または `GET /v1/tasks/{task_id}` で約 5 秒ごとに確認し続けてください。同じリクエストを送り直すと 2 つ目のタスクが作られ、別に課金されます。
2. **`progress.stage` が `finalizing`。** モデルの生成は終わり、Beatra がファイルを保存しています。Beatra は最長約 40 分間、生成も課金もやり直さずにファイルの取得を試みます。それでも取得できない場合、タスクは `model_output_invalid` で失敗し、クレジットは返金されます。
3. **呼び出しがタイムアウトした、または接続が切れた。** 同じ `client_request_id`（MCP）または `Idempotency-Key`（REST）と、まったく同じ引数で再試行してください。Beatra は新しいタスクを作らず、元のタスクを返します。タスク ID がわからなくなった場合は、先に `beatra.tasks.list` または `GET /v1/tasks` で最近のタスクを確認してください。
4. **エラーが `retryable: true`。** `Retry-After` がある場合はその時間だけ待ってから、同じリクエストを再試行してください。`429` レスポンスには `X-RateLimit-*` ヘッダーが付きます。[レート制限](https://docs.beatra.cn/ja/docs/mechanisms/rate-limits)を参照してください。
5. **プランで同時に実行できる数がすべて使われている。** 新しいリクエストは開始されず、課金もされません。どれかが終わるのを待ってから、同じリクエストを再試行してください。[同時にいくつまで](https://docs.beatra.cn/ja/docs/mechanisms/billing#同時にいくつまで)を参照してください。
6. **`model_unavailable`。** `beatra.models.list` から別のモデルを選ぶか、`model: "auto"` を指定して、利用できるモデルを Beatra に選ばせてください。
7. **キャンセルが `409` を返した。** 実行はすでに始まっており、最後まで続きます。最終状態になるまで同じタスクを確認し続けてください。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `model_timeout` | 504 | 可 | モデルへのリクエストがタイムアウトしました。バックオフして再試行してください。 |
| `model_request_failed` | 502 | 可 | 再試行可能なサービスエラーの後も、モデルへのリクエストが失敗しました。バックオフして再試行してください。続く場合は入力を調整するか、別のモデルを選んでください。 |
| `model_unavailable` | 503 | 可 | 指定したモデルは現在利用できません。バックオフして再試行するか、選択可能な別のモデル（`beatra.models.list` または `GET /v1/catalog/models`）に切り替えるか、`model=auto` を使用してください。`details.reason` と `details.available_at` がある場合は、原因と復旧予定時刻を示します。 |
| `model_rate_limited` | 429 | 可 | モデルの処理能力がレート制限されました。バックオフして再試行してください。 |
| `rate_limited` | 429 | 可 | 呼び出し元のレート制限を超えました。`Retry-After` の間隔を空けてから再試行してください。`X-RateLimit-*` ヘッダーに現在の上限が示されます。 |
| `voice_activation_daily_limit` | 429 | 不可 | このアカウントは今日すでにクローンボイスを 3 件有効化し、1 日の上限に達しました。今回は課金されていません。今日さらに有効化するには Beatra サポートにご連絡ください。上限は北京時間 08:00（UTC 0:00）にリセットされます。 |
| `request_in_progress` | 409 | 可 | 同じ冪等性の識別子を持つリクエストがまだ処理中です。後で同じ識別子で再試行すると、元のレスポンスが返されます。 |
| `conflict` | 409 | 不可 | 操作がリソースの現在の状態と競合しています。タスクのキャンセルの場合は、実行が継続されることを意味します。`details.action` に従ってください（通常は同じタスクのポーリングを続けます）。作業を再送信しないでください。 |
| `upload_stalled` | 408 | 可 | アップロードのデータ送信が長時間止まったか、アップロードの制限時間を超えました。同じアップロード URL に同じ PUT をもう一度送信してください。アップロードの許可が期限切れの場合は、`beatra.assets.upload` で新しく取得してください。 |
| `model_output_invalid` | 502 | 可 | モデルが返した結果を納品できません（音声の欠落や破損、生成ファイルを取得できない場合など）。タスクは失敗し、料金は返金されます。新しいリクエストを送信してください。 |
| `internal_error` | 500 | 可 | 分類されていないサーバー側のエラーです。同じ冪等性の識別子で再試行してください。続く場合は request_id を添えてご報告ください。 |

## パラメーターが正しくない [#invalid-parameters]

拒否されたリクエストには、問題のフィールドが示されます。`error.param` はそのフィールドを指す JSON Pointer で、`details.errors`（検証エラー）または `details.candidate_failures[]`（モデルが対応しないオプション）に、各フィールドが受け付ける値が書かれています。

1. **示されたフィールドを直し、新しい `client_request_id` で送信する。** 入力が変わったので新しい作業として扱います。古い識別子を使い回すと `idempotency_conflict` が返ります。
2. **モデルの現在の制限**（解像度、長さ、アスペクト比、入力の種類）を `beatra.models.list` または `GET /v1/catalog/models` で確認するか、`model: "auto"` を指定して、リクエスト全体に対応できるモデルを Beatra に選ばせてください。明示的に指定したモデルが別のモデルに置き換えられることはありません。
3. **メディア入力**：Beatra からアクセスできる HTTPS の URL を渡すか、`beatra.assets.upload` でファイルをアップロードし、返された `artifact_id` を渡してください。[ソース素材のアップロード](https://docs.beatra.cn/ja/docs/mechanisms/uploads)を参照してください。
4. **コンテンツの審査**：`safety_rejected` と `content_filtered` は、プロンプトまたは入力のどれかを変える必要があることを示します。同じ内容のままでは再び拒否されます。
5. **引数の一覧**：MCP ツールごとの引数は [MCP ツールリファレンス](https://docs.beatra.cn/ja/docs/mcp-tools)、REST のリクエスト本文は [API リファレンス](https://docs.beatra.cn/ja/docs/api-reference)にあります。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `invalid_request` | 422 | 不可 | リクエスト本文が構造の検証を通過しませんでした。`param` は最初に問題のあるフィールドを指し、`details.errors` にはすべての不備とその `loc`、理由が含まれます。該当するフィールドを修正して再送信してください。 |
| `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 | 不可 | リクエストが、選択したモデルのコンテキスト長を超えています。入力を短くするか、より長いコンテキストに対応するモデルを選んでください。 |
| `invalid_media` | 422 | 不可 | メディア入力の形式が正しくないか、デコードできません。ファイルを書き出し直すか再エンコードしてから、もう一度送信してください。`param` が問題のあるフィールドを示します。 |
| `unsupported_media_type` | 422 | 不可 | この機能はこのメディア形式に対応していません。対応する形式（機能ページまたはモデルの制約を参照）に変換してから再送信してください。 |
| `media_too_large` | 413 | 不可 | メディア入力がサイズの上限を超えています。入力を圧縮またはトリミングするか、先にアップロードしてアーティファクト参照を渡してください。 |
| `media_fetch_failed` | 422 | 可 | Beatra が入力リソースにアクセスできませんでした。リソースに HTTPS でアクセスできるか確認するか、アップロードしてアーティファクト参照を渡してください。 |
| `safety_rejected` | 400 | 不可 | リクエストがコンテンツの安全審査を通過しませんでした。ユーザーにプロンプトとすべての入力素材を確認してもらい、安全でない可能性のある内容を修正または差し替えたうえで、新しい client_request_id で新しいタスクとして送信してください。同じ内容で再試行しても解決しません。 |
| `content_filtered` | 502 | 不可 | 生成の途中で、安全フィルターが出力をブロックしました。プロンプトを言い換えるか、別のモデルに切り替えてください。同じ内容で再試行すると、通常は再びブロックされます。 |
| `idempotency_conflict` | 409 | 不可 | 同じ `Idempotency-Key` / `client_request_id` が、異なるリクエスト本文で使われました。内容を変えた作業は新しい識別子で送信し、同じ作業をそのまま再試行する場合は元の識別子を再利用してください。どちらにするか決める前に、既存のタスクを確認してください。 |
| `callback_url_required` | 422 | 不可 | コールバック署名キーを選択した場合は、コールバック URL が必要です。`callback_url` を追加するか、`callback_signing_key_id` を外してください。 |
| `callback_signing_key_not_found` | 404 | 不可 | コールバック署名キーが存在しないか、このアカウントからは参照できません。コンソールで署名キーの一覧を確認し、有効なキー ID を指定してください。 |
| `callback_signing_key_inactive` | 422 | 不可 | このコールバック署名キーは廃止済みのため、新しいタスクでは選択できません。有効なキーを選択するか、署名なしで配信する場合はキー ID を省略してください。 |
| `invalid_window` | 422 | 不可 | 期間の指定が無効です。 |
| `invalid_cursor` | 400 | 不可 | ページネーションのカーソルの形式が正しくありません。 |

## バージョンが合わない [#version-mismatch]

パソコンにインストールした Beatra Skill は、更新するまでインストールしたときのバージョンのままです。Skill は 1 日に最大 1 回、インストール元のストアまたはツールを確認し、新しいバージョンがあれば、更新コマンドを 1 行で表示します。

1. **手動で確認する**：Skill フォルダーで `python3 scripts/mcp_client.py update --check` を実行します。ストアで提供中のバージョンを表示するだけで、何もインストールしません。
2. **インストール元から更新し**、新しい Agent セッションを開始して新しいバージョンを読み込ませます。

   | インストール方法 | 更新方法 |
   | --- | --- |
   | Beatra のインストールメッセージ | インストールメッセージをもう一度送る |
   | skills CLI | グローバルインストールは `npx skills update <package> -g -y`、プロジェクトへのインストールはプロジェクトフォルダーで `npx skills update <package> -p -y` |
   | GitHub CLI | `gh skill update <package>` |
   | ClawHub CLI | `clawhub update <package> --workdir <dir> --dir <skills-dir>` |
   | SkillHub CLI | `skillhub install <package> --force --dir <skills-dir>` |
   | WorkBuddy | WorkBuddy で Skill を更新する |

3. **公開ソーシャルデータで `schema_hash does not match the current tool` と表示される。** Agent が引数を読み込んだ後に、ツールの引数が変わりました。`beatra.social.tools.get` をもう一度呼び出し、新しい `schema_hash` と新しい `client_request_id` で送信してください。
4. **以前に組み込んだコードが、API で提供されなくなったパスやオプションを呼び出している。** [API リファレンス](https://docs.beatra.cn/ja/docs/api-reference)と [MCP ツールリファレンス](https://docs.beatra.cn/ja/docs/mcp-tools)と照らし合わせて、呼び出しを直してください。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `skill_package_format_invalid` | 422 | 不可 | Skill パッケージの識別子の形式が正しくありません。64 文字以内の小文字とハイフンからなる slug と、有効な SemVer のパッケージバージョンを使用してください。 |
| `streaming_not_yet_implemented` | 501 | 不可 | 旧バージョンとの互換用のコードです。以前のデプロイでは `stream=true` を認識していましたが、ストリーミングは有効になっていませんでした。 |
| `not_found` | 404 | 不可 | リクエストされた HTTP リソースまたはエンドポイントが見つかりません。パスと識別子を確認してください。そのまま再試行しても成功しません。 |

## タスク、ファイル、ボイスが見つからない [#missing-resources]

`*_not_found` のコードは、その ID が存在しないか、別の Beatra アカウントに属していることを示します。タスク、ファイル、ボイスを作成したときに返された ID を使い、Agent または API キーが作成したアカウントに接続されていることを確認してください（[アカウントと統合](https://docs.beatra.cn/ja/docs/accounts)）。

- タスク：`beatra.tasks.list` または `GET /v1/tasks` で最近のタスクを確認します。
- アップロードしたファイル：もう一度アップロードし、新しく返された `artifact_id` を使います。
- ボイス：`beatra.voices.list` または `GET /v1/voices` で使えるボイスを確認します。有効化を待っているクローンボイスは 7 日後に期限切れになります。

| コード | HTTP | 再試行 | 発生する状況と対処 |
|---|---|---|---|
| `task_not_found` | 404 | 不可 | task_id が存在しないか、このアカウントのものではありません。作成時に返された task_id を使用してください。最近のタスクは `GET /v1/tasks` または `beatra.tasks.list` で一覧できます。 |
| `artifact_not_found` | 404 | 不可 | artifact_id が存在しないか、このアカウントのものではありません。メディアをもう一度アップロードし、新しく返されたアーティファクト ID を使用してください。 |
| `result_undeliverable` | 502 | 不可 | 完了した結果を返せませんでした。サイズが大きすぎる、ネストが深すぎる、または有効な JSON ではありません。同じ照会を再送信しないでください。 |
| `voice_not_found` | 404 | 不可 | voice_id が存在しないか、このアカウントのものではありません。利用できるボイスは `GET /v1/voices` または `beatra.voices.list` で一覧できます。 |
| `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_retired` | 422 | 不可 | このボイスは提供終了しました。details に推奨の代替ボイス replacement_voice_id が含まれる場合があります。Beatra がボイスを自動で置き換えることはありません。今回の料金は請求されないか、返金されます。 |
| `voice_unavailable` | 422 | 不可 | 保存されたサンプルからこのクローンボイスを復元できなくなりました。恒久的な状態のため再試行せず、サポートにお問い合わせください。今回のリクエストは請求されないか返金されます。元のクローン料金は返金されません。 |

## それでも解決しない場合 [#support]

[support@beatra.ai](mailto:support@beatra.ai) にメールするか、[コンソール](https://console.beatra.cn)の「フィードバック」からご連絡ください。次の情報を添えてください。

- エラーの `request_id`（レスポンスヘッダー `X-Request-Id` と同じ値）と、タスクがある場合はタスク ID
- エラーの `code` とメッセージ
- 発生した日時と、Skill、MCP、REST API のどれを使っていたか

API キー、`~/.beatra/` 内のファイル、認証コードはサポートには不要です。送らないでください。