# エラーコード

> BotdoorのAPIとMCPが返すすべてのエラーコードについて、HTTPステータス、意味、次に取るべき対応をまとめています。

Source: https://docs.botdoor.co/ja/help/errors/

すべてのエラーは同じ形式 `{"error": {"code", "message", "hint", "retryable", "details"}}` で返されます。処理の分岐には `code` を使ってください。リクエストで `Accept-Language: ja` を送ると `message` と `hint` は日本語で返されますが、`code` と `details` は変わらないため、プログラムでは必ず `code` で分岐してください。詳しくは[RESTの概要](https://docs.botdoor.co/ja/api/overview/)をご覧ください。

| ステータス | コード | 意味 | 対応 |
|---|---|---|---|
| 400 | `invalid_json` | リクエストボディが有効なJSONではありません。 | `Content-Type: application/json` を指定し、JSONオブジェクトを送ってください。 |
| 400 | `invalid_form` | /agentへのPOSTのボディがフォームでもJSONオブジェクトでもありません。 | フォームかJSONオブジェクトを送るか、ボディなしで送ってください。 |
| 400 | `validation_failed` | フィールドが不足しているか、形式が正しくありません。 | `details.fields` と `message` を確認してください。 |
| 400 | `invalid_date` | `scheduledFor` が実在しない日付です（例：2月31日）。 | 実在する日付を送ってください。 |
| 400 | `scheduled_in_past` | `scheduledFor` の日時がすでに過ぎています。 | 未来の日時を指定してください。 |
| 400 | `scheduled_too_far` | `scheduledFor` が1年以上先です。 | 12か月以内の日時を指定してください。 |
| 400 | `media_required` | 投稿先に画像または動画が必要です（Instagram、TikTok、YouTube、Pinterest）。 | メディアをアップロードし、`mediaIds` を指定してください。 |
| 400 | `media_unreadable` | ファイルが途中で切れているか、破損しているようです。 | ファイルを書き出し直して、再度アップロードしてください。 |
| 400 | `unsupported_media_type` | 対応している画像・動画形式ではありません。 | JPEG、PNG、GIF、WebP、MP4、MOV、WebMを使ってください。 |
| 400 | `thread_unsupported` | 投稿先がスレッドに対応していません。 | スレッドはX、Threads、Blueskyで使えます。 |
| 400 | `poll_unsupported` | 投稿先がアンケートに対応していないか、投稿にメディアが含まれています。 | アンケートはXとLinkedInで、メディアなしの場合に使えます。 |
| 400 | `first_comment_unsupported` | 投稿先が最初のコメントに対応していません。 | その投稿先では `firstComment` を外してください。 |
| 400 | `cover_unsupported` | 投稿先が動画のカバー画像に対応していません。 | その投稿先では `cover` を外してください。 |
| 400 | `tiktok_privacy_conflict` | 選択したTikTokアカウント間で共通する公開範囲がありません。 | TikTokアカウントには1つずつ投稿してください。 |
| 400 | `tiktok_ai_unsupported` | ここではAI生成ラベルを付けられません。 | `tiktokAiGenerated` を外してください。 |
| 400 | `upstream_rejected` | SNS側がコンテンツを拒否しました。 | `message` を確認し、投稿内容を修正してください。 |
| 400 | `platform_not_supported` | 不明なプラットフォーム名です。 | [ネットワーク](https://docs.botdoor.co/ja/networks/overview/)をご覧ください。 |
| 400 | `platform_coming_soon` | そのSNSはまだ利用できません。 | 別のSNSを選んでください。 |
| 400 | `platform_unavailable` | そのSNSは一時的に利用できません。 | 時間をおいて再度お試しください。 |
| 400 | `connect_requires_human` | Blueskyはアプリ内でアプリパスワードを使って連携します。 | **アカウント**ページで連携するよう、オーナーに依頼してください。 |
| 400 | `invalid_redirect` | `redirect_url` がbotdoor.co上のURLではありません。 | 省略するか、botdoor.coのURLを使ってください。 |
| 400 | `email_not_allowed` | 登録時に使い捨てまたはダミーのメールアドレスが使われました。 | オーナーの実際のメールアドレスを使ってください。 |
| 400 | `reset_invalid` | パスワード再設定リンクが使用済みか、期限切れです。 | 新しいリンクをリクエストしてください。 |
| 401 | `unauthorized` | APIキーまたはセッションがないか、正しくありません。 | `Authorization: Bearer bd_…` を送ってください。 |
| 403 | `agent_signup_closed` | ボットによる登録は現在停止しています。 | オーナーがログインしてキーを作成してください。 |
| 403 | `claim_required` | ワークスペースがまだ受け取られていません（アカウント連携時、またはアップロードが10件を超えた場合）。 | 受け取り用のメールを開くようオーナーに依頼してください。`POST /claim-link` で再送できます。 |
| 403 | `approval_requires_human` | 承認と一括承認・一括却下には、ログインした人間のユーザーが必要です。 | アプリで操作するようオーナーに依頼してください。 |
| 403 | `self_approval_forbidden` | キーは自分が作成した投稿を承認できません。 | 人間のユーザーが承認してください。 |
| 403 | `reject_not_own_post` | キーが却下できるのは、そのキー自身が作成した投稿だけです。 | 人間のユーザー、または投稿を作成したキーが却下してください。 |
| 403 | `retry_not_own_post` | キーが再試行できるのは、そのキー自身が作成した投稿だけです。 | 人間のユーザー、または投稿を作成したキーが再試行してください。 |
| 403 | `cancel_not_own_post` | APIキーがキャンセルできるのは、そのキー自身が作成した投稿だけです。 | 人間のユーザー、または投稿を作成したキーがキャンセルしてください。 |
| 403 | `delete_not_own_post` | APIキーが削除できるのは、そのキー自身が作成した投稿だけです。 | 人間のユーザーが投稿ページで削除するか、投稿を作成したキーが削除してください。 |
| 403 | `reschedule_not_own_post` | APIキーが日時を変更できるのは、そのキー自身が作成した投稿だけです。 | 人間のユーザー、または投稿を作成したキーが日時を変更してください。 |
| 403 | `session_required` | APIキーの変更にはブラウザのセッションが必要です。 | /loginでログインしてください。 |
| 403 | `cross_site_request` | Cookieを使うリクエスト（フォームやAPIの書き込み）が別のサイトから送信されました。 | botdoor.coから送信するか、APIキーを使ってください。 |
| 403 | `plan_limit_reached` | プランのアカウント数の上限に達しています。 | いずれかのアカウントの連携を解除するか、アップグレードしてください。 |
| 403 | `plan_feature_unavailable` | この機能はご利用のプランに含まれていません（XにはSoloまたはAgencyが必要です）。 | アップグレードしてください。 |
| 403 | `post_limit_reached` | Freeプランの今月の30投稿を使い切りました。 | 翌月1日（UTC）まで待つか、アップグレードしてください。 |
| 403 | `wrong_password` | 現在のパスワードが正しくありません（設定）。 | 正しいパスワードで再度お試しください。 |
| 404 | `not_found` | 該当するルートがありません。 | パスを確認してください。 |
| 404 | `post_not_found` | このワークスペースに、このIDの投稿はありません。 | `GET /posts` で投稿の一覧を取得してください。 |
| 404 | `media_not_found` | メディアIDがこのワークスペースに存在しません。 | 先に `POST /media` でアップロードしてください。 |
| 404 | `account_not_found` | アカウントIDがこのワークスペースに存在しません。 | `GET /accounts` でアカウントの一覧を取得してください。 |
| 404 | `preview_not_found` | このメディアにはプレビューがありません。 | 代わりに `url` を使ってください。 |
| 409 | `no_accounts_connected` | まだアカウントが連携されていません。 | 先にアカウントを連携してください。 |
| 409 | `account_needs_reconnection` | SNS側がアクセスを取り消しました。 | アカウントを再連携してください。 |
| 409 | `media_expired` | アップロードから7日以上経過しています。 | 再度アップロードしてください。 |
| 409 | `duplicate_content` | 過去24時間以内に、同じテキストとメディアがそのアカウントに投稿されています。 | 投稿内容または投稿先アカウントを変更してください。 |
| 409 | `tiktok_cannot_post` | TikTokから、このクリエイターは現在投稿できないと返されました。 | 時間をおいてリトライしてください（retryable）。 |
| 409 | `not_awaiting_approval` | この投稿はすでに承認待ちではありません。 | 投稿を取得してステータスを確認してください。 |
| 409 | `schedule_passed` | 承認される前に予約日時が過ぎました。投稿は行われていません。 | `publishNow` または新しい `scheduledFor` を指定して承認してください。 |
| 409 | `not_cancellable` | この投稿はすでに公開済みか、承認・却下が決定しています。 | キャンセルするものはありません。 |
| 409 | `not_deletable` | 投稿の一部が公開済み、予約済み、または送信中です。 | 削除できるのは一度も送信されていない投稿だけです。予約済みの投稿は先にキャンセルしてください。 |
| 409 | `not_reschedulable` | この投稿はすでに承認待ちでも予約済みでもありません。 | 投稿を取得してステータスを確認してください。 |
| 409 | `not_retryable` | 再試行できるのは失敗した投稿だけです。 | 投稿を取得してステータスを確認してください。 |
| 409 | `first_comment_not_failed` | 最初のコメントは失敗していません。 | 再試行するものはありません。 |
| 409 | `already_claimed` | このワークスペースはすでに受け取られています。 | オーナーが/loginでログインしてください。 |
| 409 | `email_taken` | このメールアドレスのアカウントはすでに存在します（登録ページ）。 | 代わりにログインしてください。 |
| 410 | `claim_invalid` | 受け取りリンクの期限が切れたか、ワークスペースが削除されています。 | もう一度登録してください。 |
| 413 | `file_too_large` | 100 MBを超えています（MCP経由では10 MB）。 | 圧縮するか、大きなファイルはRESTを使ってください。 |
| 422 | `idempotency_key_reused` | 同じ `Idempotency-Key` で、異なるボディが送られました。 | 新しい投稿には新しいキーを使ってください。 |
| 429 | `rate_limited` | リクエストが多すぎます。待機時間は `Retry-After` で示されます。 | 待ってからリトライしてください。 |
| 500 | `internal_error` | Botdoor側で問題が発生しました。 | 同じ `Idempotency-Key` でリトライしてください。 |
| 500 | `idempotency_conflict` | 同じキーを使った2つのリクエストが競合しました。 | リトライしてください。保存済みの投稿が返されます。 |
| 502 | `upstream_auth_failed` | 投稿プロバイダーがBotdoorの認証情報を拒否しました。 | 時間をおいてリトライしてください。Botdoorにはアラートが届いています。 |
| 502 | `upstream_unavailable` | 投稿プロバイダーが停止しているか、応答が遅くなっています。 | 時間をおいてリトライしてください（retryable）。 |
| 503 | `upstream_payment_required` | プロバイダー側でBotdoorの請求設定が必要です。 | 時間をおいてリトライしてください。Botdoorにはアラートが届いています。 |
| 503 | `signup_capacity` | 本日の登録数の上限に達しました。 | 明日もう一度お試しください。 |

## よくある質問

### エラーが発生したら毎回リトライすべきですか？

いいえ。リトライするのは、retryableがtrueの場合、429でRetry-Afterの秒数を待った後、または5xxで同じIdempotency-Keyを使う場合だけです。

### エラーコードは変更されませんか？

はい。コードは変わりません。ただし、messageとhintの文言は変更されることがあります。

### MCPツールも同じエラーコードを使いますか？

はい。MCPでは、同じ形式のエラーがisErrorをtrueにしたツール結果として返されます。

### リトライによって二重に投稿されることはありますか？

同じIdempotency-Key（REST）またはidempotencyKey（MCP）を送れば、二重に投稿されることはありません。