Lỗi MCP Server

Cách xử lý các lỗi được trả về bởi foura-mcp server.

Mọi phản hồi lỗi từ bất kỳ công cụ nào trong bốn công cụ (foura_auto, foura_single, foura_proxy, foura_browser) đều có cấu trúc. Các LLM agent có thể đọc trường code cho logic retry mà không cần phân tích cú pháp văn bản.

Cấu trúc envelope

Mọi lỗi (isError: true) đều chứa một khối structuredContent. Các trường tối thiểu trên mọi lỗi:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

Đối với các lỗi upstream có trạng thái HTTP, status cũng sẽ có mặt. Đối với các lỗi giới hạn tốc độ và dung lượng, phong bì sẽ thêm retryAfter, current.{concurrency, rpm} và limits.{maxConcurrency, maxRpm}, cùng định dạng với lỗi REST API cơ bản.

Các giá trị code ổn định

Các lỗi cấp HTTP từ máy chủ MCP

Một số lỗi xảy ra ở lớp truyền tải MCP, trước khi bất kỳ công cụ nào được gọi. Chúng trả về lỗi JSON-RPC thô (không có structuredContent):

Các danh sách cho phép đối với lỗi 403 có thể định cấu hình qua môi trường cho những người tự lưu trữ (self-host) thông qua FOURA_MCP_ALLOWED_HOSTS và FOURA_MCP_ALLOWED_ORIGINS.

Các browser profile bị từ chối

Một browser profile mà danh mục không thể cung cấp, hoặc một profile được gửi với unblocker được đặt thành false, sẽ trả về lỗi upstream với lý do trong error và request đó không bao giờ rời khỏi FourA. Thông báo sẽ liệt kê những gì khả dụng, vì vậy hãy thử lại với một trong các tổ hợp được liệt kê thay vì dùng lại tổ hợp cũ.

Đây là các trường hợp từ chối, không phải lỗi hệ thống (outages): việc thử lại request giống hệt sẽ không thể thành công và không có trình duyệt nào khác được sử dụng để thay thế.

Chiến lược retry

Bốn nhóm:

• Chờ và thử lại: rate_limited, at_capacity, service_unavailable, upstream_error. Tôn trọng retryAfter nếu có. Sử dụng exponential backoff với jitter khi không có.
• Giữ nguyên phạm vi và thử lại sau: no_eligible_proxy. Không gỡ bỏ exitCountries hoặc ngầm thay thế bằng một quốc gia khác. Chỉ thay đổi hoặc mở rộng allowlist khi người dùng thay đổi yêu cầu một cách rõ ràng.
• Không thử lại cho đến khi input hoặc credential được sửa: bad_request, auth_failed, not_found, ssrf_blocked. Đối với auth_failed, hãy xác minh API key của FourA, không phải thông tin xác thực của trang đích.
• Chuyển đổi công cụ khi nội dung yêu cầu: forbidden trên foura_single có thể biện minh cho một lần thử foura_proxy có giới hạn. Sử dụng foura_browser khi nội dung mong muốn cần JavaScript. Sau khi chọn proxy thành công, hãy truyền ID proxy được trả về vào foura_browser.proxy thay vì bắt đầu một lựa chọn mới.

Ví dụ về retry (TypeScript, phía 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");
}

Liên quan

• MCP Server, bốn công cụ và schema của chúng
• MCP Recipes, các prompt workflow đi kèm với server
• API Errors, cùng một envelope ở tầng REST API bên dưới