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 后,将返回的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,四个工具及其 Schema
- MCP Recipes,随服务器提供的运行流提示词
- API 错误,底层 REST API 层相同的封装结构
- 速率限制,
rate_limited和at_capacity背后的账户与平台限制