# MCP Server Errors

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

如何处理 [foura-mcp server](https://foura.ai/docs/mcp/server) 返回的错误。

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

## Envelope 结构

每个错误（`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 时间午夜重置。`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`](https://foura.ai/docs/api/endpoints#browser-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 端)

```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)，四个工具及其 Schema
- [MCP Recipes](https://foura.ai/docs/mcp/recipes)，随服务器提供的运行流提示词
- [API 错误](https://foura.ai/docs/api/errors)，底层 REST API 层相同的封装结构
- [速率限制](https://foura.ai/docs/api/rate-limits)，`rate_limited` 和 `at_capacity` 背后的账户与平台限制
