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 の選択が成功した後は、新しく選択を開始するのではなく、返されたproxyID を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の背景にあるアカウントとプラットフォームの制限