# Lỗi

> Toàn bộ mã lỗi của MCP và REST API X-Buddy, trạng thái HTTP, khả năng thử lại an toàn và cách xử lý từng lỗi.

Source: https://x.builera.app/docs/vi/errors
Last checked: 2026-10-24

MCP và REST dùng chung một danh sách mã lỗi. Hãy đối chiếu theo `code`, không bao giờ dựa vào nội dung thông báo.

## REST {#rest}

Lỗi dùng định dạng `application/problem+json` (RFC 9457):

```json
{
  "type": "https://reach-link-craft.lovable.app/docs/api#error-revision_conflict",
  "title": "Someone changed this setting since you read it. Read it again and retry.",
  "status": 412,
  "code": "revision_conflict",
  "message": "Someone changed this setting since you read it. Read it again and retry.",
  "retryable": false,
  "request_id": "req_…",
  "revision": 4,
  "current": {}
}
```

Mọi phản hồi đều có header `X-Request-Id`. Lỗi có `retry_after_s` cũng gửi kèm `Retry-After`.

## MCP {#mcp}

Kết quả tool có `isError: true` và phần văn bản là cùng nội dung JSON đó, nhưng không có các trường bao ngoài của REST là `type`, `title` và `status`.

## Các trường {#fields}

| Trường | Khi nào |
|---|---|
| `code`, `message`, `retryable` | Luôn có. |
| `retry_after_s` | Chờ khoảng thời gian này trước khi thử lại. |
| `next_action` | Gợi ý việc cần làm tiếp theo. |
| `field` | Trường đầu vào bị sai. |
| `detail` | Chi tiết bổ sung, ví dụ: điều kiện tiên quyết nào không được đáp ứng. |
| `candidates` | Với `ambiguous_account`: các lựa chọn `{ account_id, handle, label }`. |
| `revision`, `current` | Với `revision_conflict`: số phiên bản đã lưu và đối tượng hiện tại. |
| `request_id` | Cung cấp giá trị này khi báo cáo sự cố. |

## Tất cả mã lỗi {#all-error-codes}

| Mã | Mã HTTP | Tự thử lại được | Cách xử lý |
|---|---|---|---|
| [`unauthorized`](/docs/vi/errors/unauthorized) | 401 | Không | Thiếu hoặc sai khoá. REST: gửi `Authorization: Bearer <khoá API>`. MCP: kết nối lại để đăng nhập OAuth. Không thử lại cùng khoá sai. |
| [`connection_not_linked`](/docs/vi/errors/connection_not_linked) | 403 | Không | Ứng dụng AI đã đăng nhập nhưng chưa gắn workspace. Kết nối lại và chọn workspace trên trang đồng ý của X-Buddy. |
| [`integration_paused`](/docs/vi/errors/integration_paused) | 403 | Không | Kết nối này đang tạm dừng trong X-Buddy (Cài đặt → Kết nối MCP / API). Chủ hoặc Quản lý bật lại rồi mới gọi tiếp. |
| [`workspace_integrations_paused`](/docs/vi/errors/workspace_integrations_paused) | 403 | Không | Workspace đang tạm dừng mọi kết nối MCP / API. Chủ hoặc Quản lý bật lại trong Cài đặt → Kết nối MCP / API. |
| [`integration_revoked`](/docs/vi/errors/integration_revoked) | 401 | Không | Kết nối hoặc khoá đã bị thu hồi. Tạo khoá mới hoặc kết nối lại; không thử lại. |
| [`integration_authorization_lost`](/docs/vi/errors/integration_authorization_lost) | 403 | Không | Người tạo kết nối không còn quyền này (đổi vai trò hoặc rời workspace). Dùng kết nối của người có quyền hiện tại. |
| [`key_expired`](/docs/vi/errors/key_expired) | 401 | Không | Khoá API đã hết hạn. Tạo khoá mới trong Cài đặt → Kết nối MCP / API. |
| [`workspace_suspended`](/docs/vi/errors/workspace_suspended) | 403 | Không | Workspace đang bị đình chỉ nên không chạy thao tác nào. Liên hệ chủ workspace. |
| [`forbidden`](/docs/vi/errors/forbidden) | 403 | Không | Vai trò hiện tại của người tạo kết nối không có quyền làm việc này. Xem dòng “Quyền cần có” trên trang thao tác. |
| [`read_only`](/docs/vi/errors/read_only) | 403 | Không | Kết nối này chỉ được đọc. Muốn ghi, tạo kết nối mới không bật chế độ chỉ đọc. |
| [`message_content_off`](/docs/vi/errors/message_content_off) | 403 | Không | Kết nối được liệt kê hội thoại nhưng không được đọc nội dung tin. Bật quyền đọc tin nhắn khi kết nối lại. |
| [`account_not_allowed`](/docs/vi/errors/account_not_allowed) | 403 | Không | Nick này không nằm trong danh sách nick của kết nối. Chọn nick khác hoặc sửa danh sách trong Cài đặt → Kết nối MCP / API. |
| [`not_found`](/docs/vi/errors/not_found) | 404 | Không | Không có đối tượng này trong workspace (sai id, đã xoá, hoặc thuộc workspace khác). Đọc lại danh sách rồi dùng id mới. |
| [`method_not_allowed`](/docs/vi/errors/method_not_allowed) | 405 | Không | Đường dẫn đúng nhưng sai phương thức HTTP. Xem phương thức trên trang thao tác hoặc trong OpenAPI. |
| [`unknown_operation`](/docs/vi/errors/unknown_operation) | 404 | Không | Không có thao tác hoặc đường dẫn này. Dùng `tools_search` (MCP) hoặc OpenAPI để tìm đúng tên. |
| [`invalid_input`](/docs/vi/errors/invalid_input) | 422 | Không | Đầu vào sai kiểu hoặc thiếu trường. Trường `field` chỉ ra chỗ sai; sửa rồi gửi lại. |
| [`ambiguous_account`](/docs/vi/errors/ambiguous_account) | 409 | Không | Nhiều nick khớp tên bạn đưa. Chọn một `account_id` trong `candidates` rồi gọi lại — X-Buddy không đoán. |
| [`idempotency_key_required`](/docs/vi/errors/idempotency_key_required) | 428 | Không | Thao tác ghi cần khoá idempotency 8–128 ký tự (A–Z a–z 0–9 . _ : -), ví dụ một UUID cho mỗi ý định. |
| [`idempotency_conflict`](/docs/vi/errors/idempotency_conflict) | 409 | Không | Khoá này đã dùng cho đầu vào khác. Mỗi ý định một khoá mới; muốn gửi lại đúng việc cũ thì dùng đúng đầu vào cũ. |
| [`idempotency_processing`](/docs/vi/errors/idempotency_processing) | 409 | Có | Lần gọi trước với cùng khoá vẫn đang chạy. Chờ `retry_after_s` giây rồi gọi lại với cùng khoá. |
| [`revision_required`](/docs/vi/errors/revision_required) | 428 | Không | Thiết lập này có phiên bản. Đọc nó trước, rồi gửi `expected_revision` (hoặc `If-Match`). |
| [`revision_conflict`](/docs/vi/errors/revision_conflict) | 412 | Không | Có người vừa đổi thiết lập. Lỗi kèm `revision` và `current`: gộp thay đổi của bạn vào `current`, rồi gửi lại với `expected_revision = revision`. |
| [`rate_limited`](/docs/vi/errors/rate_limited) | 429 | Có | Kết nối gọi quá 600 lần một phút. Chờ `retry_after_s` giây. Đây là giới hạn của API, không phải hạn mức của nick. |
| [`unsupported_by_account`](/docs/vi/errors/unsupported_by_account) | 422 | Không | Nick này không có tính năng đó trên X (ví dụ cần Premium). Dùng nick khác. |
| [`agent_too_old`](/docs/vi/errors/agent_too_old) | 422 | Không | Agent trên VPS của nick quá cũ cho thao tác này. Agent tự cập nhật khi rảnh; thử lại sau. |
| [`conflict`](/docs/vi/errors/conflict) | 409 | Không | Yêu cầu xung đột với trạng thái hiện tại (ví dụ đã tồn tại, đang chạy). Đọc lại trạng thái trước khi quyết định. |
| [`precondition_failed`](/docs/vi/errors/precondition_failed) | 422 | Không | Một điều kiện của thao tác chưa đạt (`detail` nói rõ). Xử lý điều kiện đó trước, không gửi lại ngay. |
| [`internal`](/docs/vi/errors/internal) | 500 | Có | Lỗi bất ngờ của X-Buddy. Có thể thử lại sau ít giây với cùng khoá idempotency; báo `request_id` nếu lặp lại. |