Tham chiếu
Mã lỗi
Mọi mã lỗi REST v2 / MCP: ý nghĩa, mã HTTP, có thử lại được không và nên làm gì.
Xem MarkdownTrang này sinh tự động từ mã nguồn mỗi lần phát hành.
Lỗi trả về dạng problem JSON (RFC 9457): type, title, status, code, detail, retryable và có thể retry_at, hint. Agent quyết định theo code, không theo câu chữ của detail.
Yêu cầu
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
invalid_key |
401 | Không | Thiếu khoá kết nối, khoá sai hoặc kết nối đã bị dừng / thu hồi. | Gửi đúng Authorization: Bearer tga_…; nếu khoá đã lộ hoặc mất, tạo khoá mới trong Cài đặt → Kết nối AI. |
invalid_json |
400 | Không | Thân yêu cầu không phải JSON hợp lệ. | Gửi Content-Type: application/json và một đối tượng JSON. |
method_not_allowed |
405 | Không | Sai phương thức HTTP cho địa chỉ này. | Thao tác dùng POST /ops/<mã>; đọc danh sách dùng GET. |
unknown_operation |
404 | Không | Không có thao tác với mã này. | Xem danh sách thao tác trong tham chiếu REST hoặc gọi GET /ops. |
not_found |
404 | Không | Không tìm thấy đối tượng, hoặc kết nối này không được thấy nó. | Kiểm tra ID và danh sách tài khoản được giao cho kết nối. |
idempotency_key_required |
400 | Không | Thao tác có tác động này cần header Idempotency-Key. |
Gửi một mã riêng cho mỗi việc logic; gửi lại cùng mã khi thử lại. |
invalid_idempotency_key |
400 | Không | Idempotency-Key sai định dạng. |
Dùng chuỗi 1–100 ký tự, ví dụ một UUID. |
invalid_batch |
422 | Không | Lô lệnh không hợp lệ (rỗng, quá dài hoặc sai cấu trúc). | Gửi danh sách { op, input } theo tham chiếu /batch. |
rate_limited |
429 | Có | Kết nối gửi quá số lệnh cho phép mỗi phút. | Chờ tới retry_at rồi gửi lại; có thể nâng giới hạn trong cài đặt kết nối. |
Quyền
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
scope_denied |
403 | Không | Kết nối chưa được giao nhóm việc (scope) mà thao tác cần. | Nhờ chủ workspace thêm scope ghi trong detail cho kết nối. |
role_denied |
403 | Không | Vai trò của kết nối không đủ cho thao tác này. | Nâng vai trò kết nối (không vượt vai trò người tạo). |
creator_gone |
403 | Không | Người tạo kết nối không còn trong workspace nên kết nối mất quyền. | Một thành viên còn trong workspace cần tạo lại kết nối. |
forbidden_by_policy |
403 | Không | Chính sách của kết nối cấm loại việc nguy hiểm này. | Đổi chính sách việc nguy hiểm trong cài đặt kết nối nếu thật sự cần. |
forbidden |
403 | Không | Hệ thống từ chối vì thiếu quyền. | Kiểm tra vai trò và scope của kết nối. |
account_denied |
403 | Không | Thao tác chạm tới tài khoản Telegram không được giao cho kết nối. | Chỉ dùng tài khoản trong whoami, hoặc nhờ chủ workspace giao thêm. |
needs_all_accounts |
403 | Không | Việc này (máy, proxy, việc toàn workspace) chỉ dành cho kết nối được giao mọi tài khoản. | Dùng kết nối có quyền trên toàn bộ tài khoản. |
scope_exceeds_owner |
403 | Không | Không thể giao cho kết nối nhiều quyền hơn người tạo nó. | Bỏ các scope vượt quyền người tạo. |
Xác nhận của người dùng
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
confirmation_required |
409 | Không | Việc nguy hiểm cần người dùng đồng ý trước khi chạy. | Đưa summary cho người dùng; chỉ khi họ đồng ý mới gọi lại đúng dữ liệu cũ kèm confirm_token. |
confirmation_missing |
403 | Không | Mã xác nhận không đúng hoặc không tồn tại. | Gọi lại không kèm mã để nhận yêu cầu xác nhận mới. |
confirmation_mismatch |
403 | Không | Mã xác nhận được cấp cho một việc khác (dữ liệu vào đã đổi). | Gửi lại đúng dữ liệu đã được duyệt, hoặc xin xác nhận mới. |
confirmation_expired |
403 | Không | Mã xác nhận đã hết hạn. | Xin người dùng xác nhận lại. |
confirmation_denied |
403 | Không | Người dùng đã từ chối việc này. | Không thử lại; hỏi người dùng muốn làm gì khác. |
confirmation_used |
403 | Không | Mã xác nhận đã được dùng một lần. | Mỗi lần đồng ý chỉ cho một lần chạy; xin xác nhận mới nếu cần chạy lại. |
plan_not_found |
422 | Không | Không tìm thấy bản kế hoạch đã chuẩn bị. | Chuẩn bị lại kế hoạch rồi áp dụng. |
plan_expired |
422 | Không | Bản kế hoạch đã hết hạn. | Chuẩn bị lại kế hoạch. |
plan_used |
422 | Không | Bản kế hoạch đã được áp dụng. | Đọc lại cấu hình hiện tại thay vì áp dụng lần nữa. |
plan_mismatch |
422 | Không | Cấu hình đã đổi sau khi kế hoạch được chuẩn bị. | Chuẩn bị lại kế hoạch trên cấu hình mới. |
Ngân sách của kết nối
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
budget_exhausted |
429 | Có | Kết nối đã dùng hết ngân sách trong ngày cho nhóm việc này. | Chờ tới retry_at, hoặc nhờ chủ workspace nâng ngân sách của kết nối. |
budget_unavailable |
503 | Có | Chưa kiểm được ngân sách nên việc ghi được giữ lại (an toàn trước). | Thử lại sau retry_at. |
Xung đột
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
idempotency_mismatch |
409 | Không | Cùng Idempotency-Key nhưng dữ liệu vào khác lần đầu. |
Dùng mã mới cho việc mới; giữ mã cũ chỉ khi gửi lại đúng việc cũ. |
idempotency_in_progress |
409 | Có | Yêu cầu đầu tiên với mã này vẫn đang chạy. | Chờ một chút rồi gửi lại cùng mã để nhận kết quả đầu tiên. |
idempotency_conflict |
409 | Không | Không giữ được mã idempotency (ghi đồng thời). | Gửi lại cùng mã sau giây lát. |
conversation_locked |
409 | Có | Hội thoại đang được người hoặc kết nối khác giữ. | Chờ khoá hết hạn, hoặc nhờ người giữ nhả hội thoại. |
revision_conflict |
409 | Không | Cấu hình đã bị người khác sửa trước. | Đọc lại bản mới nhất rồi áp dụng thay đổi trên đó. |
stale_conversation |
409 | Không | Hội thoại có tin mới sau lần đọc cuối của kết nối. | Đọc tin mới rồi quyết định có trả lời nữa không. |
loop_suspected |
429 | Có | Có dấu hiệu vòng lặp tự trả lời nên việc gửi bị tạm dừng. | Kiểm tra luật tự động / agent của bạn; thử lại sau until. |
Dữ liệu vào
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
invalid_input |
422 | Không | Dữ liệu vào không đúng schema của thao tác. | Xem issues trong câu trả lời và các trường trong tham chiếu thao tác. |
invalid_cursor |
422 | Không | Con trỏ sự kiện không hợp lệ. | Dùng đúng cursor lần trước trả về, hoặc bỏ trống để đọc từ đầu. |
invalid_type |
422 | Không | Có loại sự kiện không tồn tại trong bộ lọc. | Dùng tên trong tham chiếu sự kiện. |
invalid_steps |
422 | Không | Các bước của chuỗi không hợp lệ. | Sửa các bước theo detail rồi lưu lại. |
unknown_action |
422 | Không | Loại việc không còn được hỗ trợ. | Dùng thao tác hiện có trong tham chiếu. |
dns_blocked |
422 | Không | Địa chỉ webhook trỏ tới mạng nội bộ hoặc địa chỉ bị cấm. | Dùng một địa chỉ HTTPS công khai. |
dns_failed |
422 | Có | Không phân giải được tên miền của webhook. | Kiểm tra DNS rồi thử lại. |
Trạng thái hệ thống
| Mã | HTTP | Thử lại được | Ý nghĩa | Làm gì |
|---|---|---|---|---|
rejected |
422 | Không | Server từ chối việc này (lý do trong detail). |
Đọc detail, sửa nguyên nhân rồi thử lại. |
frozen |
422 | Không | Đối tượng đang bị khoá sửa (đang chạy hoặc đã lưu trữ). | Dừng hoặc tạo bản mới rồi sửa. |
account_gone |
422 | Không | Tài khoản Telegram của việc này không còn. | Chọn tài khoản khác. |
webhook_suspended |
403 | Không | Webhook đang bị tạm dừng. | Bật lại webhook sau khi bên nhận đã chạy ổn. |
events_unavailable |
422 | Có | Sổ sự kiện tạm thời chưa đọc được. | Thử lại sau giây lát. |
enqueue_failed |
422 | Có | Không xếp được việc vào hàng đợi. | Thử lại; nếu lặp lại, xem trang Cảnh báo. |
bot_unauthorized |
422 | Không | Token bot không còn hợp lệ. | Lấy lại token qua @BotFather của tài khoản tạo bot. |
bot_update_failed |
422 | Có | Telegram chưa nhận thay đổi hồ sơ bot. | Thử lại sau giây lát. |
error |
422 | Có | Lỗi không mong đợi khi chạy thao tác. | Thử lại; nếu vẫn lỗi, gửi operation_id cho người quản trị. |