MCP Server 错误

如何处理 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 错误相同。

当您套餐自身的限制拒绝调用时，错误代码即为该限制：plan_limit_ 后面跟随 credits、bandwidth、rate、concurrency、browser_daily、premium 或 feature。若等待可以解除限制，retryAfter 会携带等待时间；对于等待无法解除的限制（例如套餐未包含的功能），则不存在该字段。plan_limit_browser_daily 同样不包含 retryAfter：它会在 UTC 时间午夜重置。

在 foura_auto 上，阶梯内达到的套餐限制会作为 rate_limited 或 forbidden 返回，并在 reason 中附带套餐代码。

稳定的 code 值

来自 MCP 服务器的 HTTP 级别错误

某些故障发生在 MCP 传输层，在调用任何工具之前。这些故障会返回原始 JSON-RPC 错误（无 structuredContent）：

403 的白名单可供自托管用户通过环境变量 FOURA_MCP_ALLOWED_HOSTS 和 FOURA_MCP_ALLOWED_ORIGINS 进行配置。

拒绝的浏览器 profile

目录中无法提供的浏览器 profile，或将 unblocker 设置为 false 发送的 profile，会作为上游故障返回并在 error 中指明原因，request 绝不会离开 FourA。错误消息中会列出可用项，因此请改用列出的组合之一重试，而非使用相同的组合。

这些属于拒绝而非服务中断：重试完全相同的 request 无法成功，且系统未替换使用任何其他浏览器。

重试策略

分为五类：

• 被你自己的计划拒绝，而非目标站点：任何 plan_limit_* 状态码。通过其他工具执行相同的操作也会被拒绝，因此切换 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 key，而非目标站点的凭据。
• 内容需要时切换工具：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 背后的账户及平台限制