# MCPサーバーエラー

> URL: https://foura.ai/ja/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

[foura-mcp server](https://foura.ai/docs/mcp/server)から返されるエラーの処理方法。

4つのツール (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) からのすべてのエラーresponseは構造化されています。LLM agentは自然言語の文章をパースすることなく、`code`フィールドを読み取ってリトライロジックを実行できます。

## エンベロープの構造

すべてのエラー (`isError: true`) は`structuredContent`ブロックを含みます。各エラーに含まれる最小限のフィールドは以下のとおりです:

```json
{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}
```

HTTPステータスを伴うアップストリームエラーの場合、`status`も存在します。プラットフォームの共有割当によって呼び出しが拒否された場合、エンベロープには`retryAfter`、`current.{concurrency, rpm}`、`limits.{maxConcurrency, maxRpm}`が追加されます。これは基盤となる[REST API errors](https://foura.ai/docs/api/errors)と同じ形式です。

プラン固有の制限によって呼び出しが拒否された場合、コードはその制限自体を示します: `plan_limit_`の後に`credits`、`bandwidth`、`rate`、`concurrency`、`browser_daily`、`premium`、または`feature`が続きます。待機によって解消される場合は`retryAfter`に待機時間が含まれます。プランに含まれていない機能など、待機しても解消されない制限の場合は含まれません。`plan_limit_browser_daily`にも`retryAfter`は含まれません (UTC午前0時にリセットされます)。`plan_limit_credits`および`plan_limit_bandwidth`は`retryAfter`を最大24時間までに制限し、請求期間の正確な終了時刻である`resets_at`を追加するため、リトライをスケジュールする前に`resets_at`を確認してください。

`foura_auto`では、ラダー内でプランの制限に達した場合、`rate_limited`または`forbidden`として返され、プランのコードが`reason`に含まれます。

## 安定した`code`値

| コード | HTTP | 意味 | リトライ可能か |
|---|---|---|---|
| `ssrf_blocked` | 該当なし | ターゲットがプライベートまたは予約済みアドレス (RFC 5735, RFC 6598, IPv6 予約済み) であるか、URL が http(s) ではないか、ホスト名が解決されませんでした | 不可、URL を確認してください。一時的に失敗した名前解決であればリトライ可能です |
| `upstream_non_json` | 変動 | アップストリームが有効な JSON ではないボディを返しました | 状況による、調査が必要です |
| `output_validation_failed` | 該当なし | MCP サーバーの `outputSchema` がアップストリームのレスポンスを拒絶したか、ツールが呼び出しを完了できませんでした (API キー未設定、API 接続不可) | 状況による: 設定を確認後、報告してください |
| `bad_request` | 400 | 入力形式が FourA API に拒絶されたか、ターゲット URL がページではなく FourA 自体の API を指しているか (取得可能なのは `/inspect` のみ)、URL 内にエンコードされていないスペースが含まれているか (`%20` としてエンコードが必要)、`proxy` で呼び出しが使用できないイグジットが指定されています: プレミアムトラフィック消費後のプレミアムイグジットは `Managed exit: this proxy id cannot be pinned to a request` を返します。取得や課金は行われません | 不可、引数を修正してください |
| `auth_failed` | 401 | FourA API キーが見つからない、無効、または無効化されています。ターゲットサイトの認証情報は関係ありません | 不可、FourA キーを修正してください |
| `forbidden` | 403 | ターゲットが 403 を返し、`validate` がそれを拒絶しました (サイトのチェック、国制限など) | 不可、または `foura_proxy` に切り替えてください |
| `not_found` | 404 | ターゲット URL またはエンドポイントが存在しません | 不可 |
| `rate_limited` | 429 | プラットフォーム共有の 1 分あたりの許容量、またはターゲットからの 429 を `validate` が拒絶しました。`foura_auto` では、プランのクレジット、トラフィック、またはレート制限である可能性もあります (`reason` を参照) | 可能、`retryAfter` が存在する場合は待機し、それ以外はバックオフしてください |
| `at_capacity` | 503 | 同時実行数上限に達したか (`current.concurrency` > `limits.maxConcurrency`)、メンテナンスのためサービスが停止しています (`error` は `Service disabled`、`retryAfter` は 60) | 可能、`retryAfter` 秒待機してください |
| `service_disabled` | 503 | 予約済み。現在、メンテナンスによるサービス停止は `at_capacity` として返され、プランに含まれないツールは `plan_limit_feature` として返されます | サポートにお問い合わせください |
| `service_unavailable` | 503 | アップストリームからの汎用 503 | 可能、短いバックオフを行ってください |
| `upstream_error` | 500+ または 0 | ターゲットがサーバーエラーを返したか、`foura_proxy` 上で `foura_browser` および `foura_auto` が応答しませんでした | 可能、指数バックオフを行ってください |
| `upstream_client_error` | 4xx | 上記に含まれないその他の 4xx | 通常は不可 |
| `upstream_unknown` | その他 | リクエストは実行されましたが、受理可能な応答が得られませんでした: `foura_single` ではターゲットが無応答 (タイムアウト、接続拒否) であり、いずれのツールでも `validate` が 2xx または 3xx のレスポンスを拒絶しました。`status` と `error` を確認してください | 調査が必要です |
| `no_eligible_proxy` | 該当なし | 厳格な `exitCountries` 許可リストに一致するプロキシがありません。`details.exitCountries` には正規化されたスコープが含まれます | 後でリトライしてください。スコープの変更は明示的な場合のみ行ってください |
| `plan_limit_credits` | 429 | プランの月間クレジットを使い果たしました | 可能、`retryAfter` の後、またはプランを変更してください |
| `plan_limit_bandwidth` | 429 | この請求期間におけるプランのトラフィック許容量を使い果たしました | 可能、`retryAfter` の後、またはプランを変更してください |
| `plan_limit_rate` | 429 | そのエンドポイントに対するプランの 1 分あたりのリクエスト数制限です | 可能、`retryAfter` の後 |
| `plan_limit_concurrency` | 429 | そのエンドポイントに対するプランの同時リクエスト数制限です | 可能、`retryAfter` の後 |
| `plan_limit_browser_daily` | 429 | プランの 1 日の Browser 許容量を使い果たしました | 可能、明日以降、または `foura_single` / `foura_proxy` を使用してください |
| `plan_limit_premium` | 403 | プレミアムイグジットを含まないプランで `exitClass: "premium"` を送信しました | 不可、パラメータを外すかプランを変更してください |
| `plan_limit_feature` | 403 | プランにそのエンドポイントまたは機能が含まれていません | 不可、プランを変更してください |

## MCPサーバーからのHTTPレベルエラー

一部のエラーは、ツールが呼び出される前のMCPトランスポート層で発生します。これらは生のJSON-RPCエラーを返します (`structuredContent`なし):

| HTTP | 発生条件 | 表示内容 |
|---|---|---|
| 400 | サポートされていない`MCP-Protocol-Version`ヘッダー | `Unsupported MCP-Protocol-Version: <value>. Supported (from @modelcontextprotocol/sdk): 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. Upgrade foura-mcp's SDK pin to extend.` |
| 401 | API keyなしでのツール呼び出しまたはリソース読み取り。ツールおよびプロンプトの一覧取得はAPI keyなしで動作可能 | JSON-RPCエラー + `WWW-Authenticate: Bearer realm="foura-mcp"` |
| 403 | 許可されていない`Origin`または`Host`ヘッダー (DNSリバインディング防御、CVE-2025-66414) | `Origin <value> is not in the allowlist`または`Host <value> is not in the allowlist` |
| 405 | `/mcp`上の`GET`または`DELETE` (ステートレスモード) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | 256 KBを超えるリクエストボディ | Expressのデフォルト413 |

403の許可リストは、セルフホスティング向けに`FOURA_MCP_ALLOWED_HOSTS`および`FOURA_MCP_ALLOWED_ORIGINS`で環境変数として設定可能です。

## 拒絶されたブラウザプロファイル

カタログに存在しないブラウザプロファイル、または`unblocker`が`false`に設定された状態で送信されたプロファイルは、`error`に理由が含まれる上流エラーとして返され、リクエストはFourAから送信されません。存在しない`browser`、`os`、`version`の組み合わせの場合、メッセージに利用可能な組み合わせが示されるため、同じものではなくリストされたいずれかの組み合わせでリトライしてください。不明な`profile` IDにはリストなしで`unknown profile`が返されます。[`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles)でIDを確認してください。

これらは停止ではなく拒絶です。まったく同一のリクエストを再試行しても成功せず、代わりに他のブラウザが使用されることもありません。

## リトライ戦略

5つの分類:

- **ターゲット側ではなく、自身のプランによって拒否された場合**: いずれかの `plan_limit_*` コード。`plan_limit_credits` および `plan_limit_bandwidth` はアカウント全体でカウントされるため、別のツール経由で同じ処理を実行しても同様に拒否されます。`plan_limit_rate`、`plan_limit_concurrency`、`plan_limit_browser_daily`、`plan_limit_feature` は単一の endpoint に適用されるため、その処理を実行可能な別のツールであれば実行できます。`retryAfter` が存在する場合はその経過を待ちます。存在しない場合はプランを変更する必要があります。`plan_limit_premium` は `exitClass` を削除することで自身で解消できます。
- **待機してリトライ**: `rate_limited`、`at_capacity`、`service_unavailable`、`upstream_error`。`retryAfter` がある場合はそれに従います。ない場合はジッター付きエクスポネンシャルバックオフを使用します。キューに入っているすべてのツール呼び出しを一度に再発行して対応しないでください。代わりに並列実行数を減らしてください。
- **スコープを維持して後でリトライ**: `no_eligible_proxy`。`exitCountries` を削除したり、別の国へ暗黙的に置き換えたりしないでください。ユーザーが明示的に要件を変更した場合にのみ、許可リストを変更または拡大してください。
- **入力または認証情報が修正されるまでリトライしない**: `bad_request`、`auth_failed`、`not_found`、`ssrf_blocked`。`auth_failed` については、ターゲットサイトの認証情報ではなく、FourA API キーを確認してください。
- **コンテンツが必要とする場合にツールを切り替える**: `foura_single` における `forbidden` は、制限付きの `foura_proxy` 試行を正当化できます。対象のコンテンツが JavaScript を必要とする場合は `foura_browser` を使用します。proxy の選択が成功した後は、新しく選択を開始するのではなく、返された `proxy` ID を `foura_browser.proxy` に渡してください。

## リトライ例 (TypeScript, MCP側)

```typescript
async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}
```

## 関連情報

- [MCP Server](https://foura.ai/docs/mcp/server): 4つのツールとそのスキーマ
- [MCP Recipes](https://foura.ai/docs/mcp/recipes): サーバーに同梱されているワークフロープロンプト
- [API Errors](https://foura.ai/docs/api/errors): 基盤となるREST APIレイヤーにおける共通エンベロープ
- [Rate Limits](https://foura.ai/docs/api/rate-limits): `rate_limited`および`at_capacity`の背景にあるアカウントとプラットフォームの制限
