Lập trình viên & AI agent
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.
Kiểm tra lần cuối: 24 tháng 10, 2026Bản Markdown
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
Lỗi dùng định dạng application/problem+json (RFC 9457):
{
"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
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
| 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
| Mã | Mã HTTP | Tự thử lại được | Cách xử lý |
|---|---|---|---|
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |