MCPサーバーエラー

foura-mcp serverから返されるエラーの処理方法。

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

エンベロープの構造

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

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

HTTPステータスを伴うアップストリームエラーの場合、statusも存在します。プラットフォームの共有割当によって呼び出しが拒否された場合、エンベロープにはretryAfter、current.{concurrency, rpm}、limits.{maxConcurrency, maxRpm}が追加されます。これは基盤となるREST 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で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側)

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: 4つのツールとそのスキーマ
  • MCP Recipes: サーバーに同梱されているワークフロープロンプト
  • API Errors: 基盤となるREST APIレイヤーにおける共通エンベロープ
  • Rate Limits: rate_limitedおよびat_capacityの背景にあるアカウントとプラットフォームの制限
最終更新日: 2026年11月13日