Lỗi MCP Server

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

Mọi response báo 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 rõ ràng. Các LLM agent có thể đọc trường code cho 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 mang theo 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 mã trạng thái HTTP, status cũng sẽ xuất hiện. Khi hạn mức dùng chung 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 giới hạn 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ờ nếu việc chờ có thể giải quyết được lỗi, và vắng mặt đối với giới hạn mà việc chờ không thể giải quyết, chẳng hạn như tính năng không nằm trong gói. plan_limit_browser_daily cũng không chứa retryAfter: nó sẽ được làm mới vào nửa đêm UTC. plan_limit_credits và plan_limit_bandwidth giới hạn retryAfter ở mức 24 giờ và bổ sung resets_at, thời điểm kết thúc chính xác của chu kỳ thanh toán, vì vậy hãy đọc resets_at trước khi bạn lên lịch thử lại.

Trên foura_auto, giới hạn gói bị chạm phải bên trong ladder sẽ trả về dưới dạng rate_limited hoặc forbidden, với mã của gói nằm trong reason.

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

Mã HTTP Ý nghĩa Có thể thử lại?
ssrf_blocked n/a Mục tiêu là địa chỉ riêng tư hoặc được bảo lưu (RFC 5735, RFC 6598, IPv6 bảo lưu), URL không phải là http(s), hoặc hostname không phân giải được Không, hãy kiểm tra URL. Quá trình tra cứu thất bại tạm thời có thể thử lại
upstream_non_json thay đổi Upstream trả về body không phải là JSON hợp lệ Có thể, hãy kiểm tra
output_validation_failed n/a outputSchema của MCP server đã từ chối phản hồi từ upstream, hoặc công cụ hoàn toàn không thể hoàn tất lệnh gọi (chưa cấu hình API key, API không thể truy cập) Có thể: kiểm tra thiết lập, sau đó báo cáo
bad_request 400 Cấu trúc đầu vào bị FourA API từ chối, URL mục tiêu trỏ đến chính API của FourA thay vì một trang web (chỉ có thể lấy /inspect tại đó), URL chứa khoảng trắng chưa được mã hóa (hãy mã hóa thành %20), hoặc proxy chỉ định một exit mà lệnh gọi không thể sử dụng: một exit cao cấp khi lưu lượng cao cấp của bạn đã hết sẽ trả về Managed exit: this proxy id cannot be pinned to a request. Không có dữ liệu nào được lấy hoặc bị tính phí Không, hãy sửa các đối số
auth_failed 401 FourA API key bị thiếu, không hợp lệ hoặc đã bị vô hiệu hóa; lỗi này không liên quan đến thông tin xác thực của trang mục tiêu Không, hãy sửa FourA key
forbidden 403 Mục tiêu trả về 403 và validate của bạn đã từ chối nó (kiểm tra trang web, giới hạn quốc gia) Không, hoặc chuyển sang foura_proxy
not_found 404 URL hoặc endpoint mục tiêu không tồn tại Không
rate_limited 429 Hạn mức chia sẻ mỗi phút của nền tảng, hoặc phản hồi 429 từ mục tiêu mà validate của bạn đã từ chối. Trên foura_auto, lỗi này cũng có thể do credit, lưu lượng hoặc rate limit của gói (xem reason) Có, đợi retryAfter nếu có, nếu không hãy lùi thời gian thử lại
at_capacity 503 Đạt giới hạn đồng thời (current.concurrency > limits.maxConcurrency), hoặc dịch vụ tạm tắt để bảo trì (error trả về Service disabled, retryAfter là 60) Có, đợi retryAfter giây
service_disabled 503 Được bảo lưu. Dịch vụ tạm tắt để bảo trì hiện trả về at_capacity, và công cụ không nằm trong gói của bạn sẽ trả về plan_limit_feature Liên hệ bộ phận hỗ trợ
service_unavailable 503 Lỗi 503 chung từ upstream Có, lùi thời gian thử lại ngắn
upstream_error 500+ hoặc 0 Mục tiêu trả về lỗi server, hoặc trên foura_proxy, foura_browser và foura_auto không bao giờ phản hồi Có, lùi thời gian thử lại theo cấp số nhân
upstream_client_error 4xx Các mã 4xx khác không được đề cập ở trên Thường là không
upstream_unknown khác Request đã chạy nhưng không tạo ra phản hồi được chấp nhận: trên foura_single mục tiêu không bao giờ phản hồi (hết thời gian, từ chối kết nối), và trên mọi công cụ validate của bạn đã từ chối phản hồi 2xx hoặc 3xx. Đọc status và error Kiểm tra
no_eligible_proxy n/a Không có proxy nào khớp với allowlist nghiêm ngặt exitCountries; details.exitCountries chứa scope đã chuẩn hóa Thử lại sau; chỉ thay đổi scope một cách rõ ràng
plan_limit_credits 429 Credit hàng tháng trong gói của bạn đã hết Có, sau retryAfter, hoặc nâng cấp gói
plan_limit_bandwidth 429 Hạn mức lưu lượng trong gói của bạn đã hết cho chu kỳ thanh toán này Có, sau retryAfter, hoặc nâng cấp gói
plan_limit_rate 429 Số lượng request mỗi phút trong gói của bạn cho endpoint đó Có, sau retryAfter
plan_limit_concurrency 429 Số lượng request đồng thời trong gói của bạn cho endpoint đó Có, sau retryAfter
plan_limit_browser_daily 429 Hạn mức Browser hàng ngày trong gói của bạn đã hết Có, vào ngày mai, hoặc sử dụng foura_single / foura_proxy
plan_limit_premium 403 Bạn đã gửi exitClass: "premium" trên một gói không bao gồm exit cao cấp Không, hãy bỏ tham số hoặc thay đổi gói
plan_limit_feature 403 Gói không hỗ trợ endpoint đó hoặc tính năng đó Không, hãy thay đổi gói

Lỗi cấp độ HTTP từ MCP server

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

HTTP Trường hợp Những gì bạn thấy
400 Header MCP-Protocol-Version không được hỗ trợ 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 Một lệnh gọi tool hoặc đọc tài nguyên không có API key. Việc liệt kê tool và prompt vẫn hoạt động khi không có key Lỗi JSON-RPC + WWW-Authenticate: Bearer realm="foura-mcp"
403 Header Origin hoặc Host không được phép (cơ chế phòng vệ DNS-rebinding, CVE-2025-66414) Origin <value> is not in the allowlist hoặc Host <value> is not in the allowlist
405 GET hoặc DELETE trên /mcp (chế độ stateless) Method not allowed in stateless mode. Use POST /mcp.
413 Request body > 256 KB 413 mặc định của Express

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

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

Một browser profile mà catalogue không thể cung cấp, hoặc một profile được gửi với unblocker đặt thành false, sẽ trả về dưới dạng lỗi upstream kèm lý do trong error và request sẽ không bao giờ rời khỏi FourA. Đối với tổ hợp browser, os và version không tồn tại, thông báo sẽ nêu rõ các tổ hợp hiện có, vì vậy hãy thử lại với một trong những tổ hợp được liệt kê thay vì dùng lại tổ hợp cũ. Một profile id không xác định sẽ nhận unknown profile mà không có danh sách: hãy tra cứu id tại GET /api/profiles.

Đây là các trường hợp từ chối, không phải sự cố gián đoạn dịch vụ: 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 thử lại

Năm nhóm:

  • Gói dịch vụ của chính bạn từ chối, không phải mục tiêu: bất kỳ mã plan_limit_* nào. plan_limit_credits và plan_limit_bandwidth tính trên toàn bộ tài khoản, do đó công việc tương tự thông qua công cụ khác cũng sẽ bị từ chối. plan_limit_rate, plan_limit_concurrency, plan_limit_browser_daily và plan_limit_feature áp dụng cho một endpoint, vì vậy công cụ khác vẫn có thể chạy nếu công cụ đó đáp ứng được tác vụ. Chờ hết thời gian retryAfter nếu có; nếu không thì phải đổi gói dịch vụ. Bạn có thể tự xử lý plan_limit_premium 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ó trường này. Sử dụng exponential backoff kèm jitter khi không có header đó. Đừng phản hồi bằng cách gửi lại đồng loạt mọi lệnh gọi công cụ trong hàng đợi: 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 một quốc gia khác. Chỉ thay đổi hoặc mở rộng allowlist khi người dùng yêu cầu rõ ràng.
  • Không thử lại cho đến khi dữ liệu đầu vào hoặc thông tin xác thực được sửa: bad_request, auth_failed, not_found, ssrf_blocked. Đối với auth_failed, hãy kiểm tra FourA API key, không phải thông tin đăng nhập của trang mục tiêu.
  • Chuyển đổi công cụ khi nội dung yêu cầu: forbidden trên foura_single có thể là lý do hợp lý để thử lại có giới hạn bằng foura_proxy. Sử dụng foura_browser khi nội dung mong muốn cần JavaScript. Sau khi chọn proxy thành công, truyền ID proxy nhận được vào foura_browser.proxy thay vì bắt đầu một lượt chọn mới.

Ví dụ thử lại (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");
}
  • MCP Server, bốn công cụ và schema tương ứng
  • MCP Recipes, prompt quy trình làm việc đi kèm với server
  • API Errors, cùng cấu trúc envelope ở tầng REST API cơ bản
  • Rate Limits, các giới hạn tài khoản và nền tảng đằng sau rate_limited và at_capacity
Cập nhật: 13 tháng 11, 2026