MCP Server Errors

如何处理 foura-mcp server 返回的错误。

来自这四个工具(foura_auto、foura_single、foura_proxy、foura_browser)中的每个错误 response 都是结构化的。LLM agent 可以直接读取 code 字段用于重试逻辑,无需解析自然语言文本。

Envelope 结构

每个错误(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 时间午夜重置。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 key,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 key 缺失、无效或已停用;这与目标站点的凭据无关 否,请修正 FourA key
forbidden 403 目标返回 403 且你的 validate 拒绝了该响应(站点检测、国家/地区限制) 否,或切换到 foura_proxy
not_found 404 目标 URL 或 endpoint 不存在 否
rate_limited 429 平台共享的每分钟额度耗尽,或目标返回 429 且被你的 validate 拒绝。在 foura_auto 上,这也可能是由于套餐的积分、流量或 rate limit(参见 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 不适用 没有 proxy 匹配严格的 exitCountries 允许列表;details.exitCountries 包含规范化后的范围 稍后重试;仅可显式更改范围
plan_limit_credits 429 套餐中的每月积分已耗尽 是,在 retryAfter 之后重试,或更改套餐
plan_limit_bandwidth 429 套餐在本计费周期的流量额度已耗尽 是,在 retryAfter 之后重试,或更改套餐
plan_limit_rate 429 该 endpoint 达到套餐规定的每分钟 request 限制 是,在 retryAfter 之后重试
plan_limit_concurrency 429 该 endpoint 达到套餐规定的并发 request 限制 是,在 retryAfter 之后重试
plan_limit_browser_daily 429 套餐的每日 Browser 额度已耗尽 是,明天重试,或使用 foura_single / foura_proxy
plan_limit_premium 403 在不包含高级出口的套餐中发送了 exitClass: "premium" 否,请移除该参数或更改套餐
plan_limit_feature 403 套餐不包含该 endpoint 或该功能 否,请更改套餐

来自 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 密钥进行工具调用或资源读取。获取工具和提示列表无需密钥 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。

这些属于拒绝而非服务中断:重试完全相同的请求无法成功,且不会使用其他浏览器替代。

重试策略

分为五类:

  • 拒绝请求的是你自己的套餐,而非目标站:任何 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 或静默替换为其他国家。仅当用户明确更改需求时,才修改或放宽 allowlist。
  • 在修复输入或凭据之前不要重试: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,四个工具及其 Schema
  • MCP Recipes,随服务器提供的运行流提示词
  • API 错误,底层 REST API 层相同的封装结构
  • 速率限制,rate_limited 和 at_capacity 背后的账户与平台限制
更新于: 2026年11月13日