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_creditsvàplan_limit_bandwidthtí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_dailyvà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 gianretryAfternếu có; nếu không thì phải đổi gói dịch vụ. Bạn có thể tự xử lýplan_limit_premiumbằng cách bỏexitClass. - Chờ và thử lại:
rate_limited,at_capacity,service_unavailable,upstream_error. Tuân thủretryAfterkhi 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óaexitCountrieshoặ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ớiauth_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:
forbiddentrênfoura_singlecó thể là lý do hợp lý để thử lại có giới hạn bằngfoura_proxy. Sử dụngfoura_browserkhi nội dung mong muốn cần JavaScript. Sau khi chọn proxy thành công, truyền IDproxynhận được vàofoura_browser.proxythay 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");
}
Liên quan
- 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_limitedvàat_capacity