# Lỗi MCP Server

> URL: https://foura.ai/vi/docs/mcp/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Cách xử lý lỗi được trả về bởi [foura-mcp server](https://foura.ai/docs/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:

```json
{
  "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](https://foura.ai/docs/api/errors) 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`](https://foura.ai/docs/api/endpoints#browser-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)

```typescript
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](https://foura.ai/docs/mcp/server), bốn công cụ và schema tương ứng
- [MCP Recipes](https://foura.ai/docs/mcp/recipes), prompt quy trình làm việc đi kèm với server
- [API Errors](https://foura.ai/docs/api/errors), cùng cấu trúc envelope ở tầng REST API cơ bản
- [Rate Limits](https://foura.ai/docs/api/rate-limits), các giới hạn tài khoản và nền tảng đằng sau `rate_limited` và `at_capacity`
