Lỗi MCP Server

Cách xử lý các lỗi do foura-mcp server trả về.

Mọi error response 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 để thực hiện logic retry mà không cần phân tích văn bản tự nhiê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 kèm HTTP status, status cũng sẽ xuất hiện. Khi hạn mức chia sẻ của nền tảng từ chối một lệnh gọi, envelope sẽ bổ sung retryAfter, current.{concurrency, rpm} và limits.{maxConcurrency, maxRpm}, có cấu trúc tương tự như lỗi REST API cơ bản.

Khi một trong các giới hạn riêng thuộc gói của bạn từ chối lệnh gọi, mã lỗi CHÍNH LÀ giới hạn đó: plan_limit_ theo sau bởi credits, bandwidth, rate, concurrency, browser_daily, premium hoặc feature. retryAfter chứa thời gian chờ trong trường hợp việc chờ đợi có thể giải phóng giới hạn, và sẽ không xuất hiện đối với giới hạn mà việc chờ đợi không thể xử lý, chẳng hạn như tính năng không nằm trong gói đăng ký. plan_limit_browser_daily cũng không chứa retryAfter: giới hạn này sẽ được làm mới vào lúc nửa đêm UTC.

Trên foura_auto, giới hạn gói đạt đến trong ladder của nó sẽ trả về dưới dạng rate_limited hoặc forbidden, cùng với mã lỗi của gói trong reason.

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

Lỗi cấp HTTP từ MCP server

Một số lỗi xảy ra tại tầng transport của MCP, trước khi bất kỳ tool nào được gọi. Những trường hợp này trả về lỗi JSON-RPC thô (không có structuredContent):

Allowlist cho lỗi 403 có thể cấu hình qua biến môi trường cho người tự host qua FOURA_MCP_ALLOWED_HOSTS và FOURA_MCP_ALLOWED_ORIGINS.

Profile trình duyệt bị từ chối

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

Đây là sự từ chối, không phải sự cố gián đoạn dịch vụ: việc thử lại một request y hệt không thể thành công, và không có trình duyệt nào khác được dùng để thay thế.

Chiến lược retry

Năm nhóm:

• Gói dịch vụ của chính bạn đã từ chối, không phải máy chủ đích: bất kỳ mã plan_limit_* nào. Thao tác tương tự thông qua một tool khác cũng sẽ bị từ chối, vì vậy việc đổi endpoint chỉ làm mất thời gian. Hãy chờ hết retryAfter nếu có; nếu không thì cần phải thay đổi gói dịch vụ. plan_limit_premium là lỗi bạn có thể tự xử lý bằng cách bỏ exitClass.
• Chờ và thử lại: rate_limited, at_capacity, service_unavailable, upstream_error. Tuân thủ retryAfter khi có. Sử dụng exponential backoff kèm jitter khi không có header này. Đừng xử lý bằng cách gửi lại đồng loạt mọi lệnh gọi tool đang chờ: thay vào đó hãy giảm số lượng lệnh chạy song song.
• Giữ nguyên phạm vi và thử lại sau: no_eligible_proxy. Không tự ý xóa exitCountries hoặc âm thầm thay thế bằng quốc gia khác. Chỉ thay đổi hoặc mở rộng allowlist khi người dùng yêu cầu thay đổi rõ ràng.
• Không thử lại cho đến khi input hoặc thông tin xác thực được khắc phục: bad_request, auth_failed, not_found, ssrf_blocked. Đối với auth_failed, hãy kiểm tra API key của FourA, không phải thông tin xác thực của trang đích.
• Đổi tool khi nội dung yêu cầu: forbidden trên foura_single có thể là lý do hợp lý để thử foura_proxy với giới hạn. Dùng foura_browser khi nội dung cần lấy yêu cầu JavaScript. Sau khi chọn proxy thành công, hãy truyền proxy ID nhận được vào foura_browser.proxy thay vì bắt đầu một lượt chọn mới.

Ví dụ 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 quy trình làm việc đi kèm với server
• API Errors, cùng định dạng envelope ở tầng REST API cơ bản
• Rate Limits, giới hạn tài khoản và nền tảng đằng sau rate_limited và at_capacity