---
title: "Mã lỗi"
locale: vi
url: https://tlg.builera.app/docs/reference/errors
verified: 2026-10-24
app_version: "2.0"
generated: true
---

# 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ì.

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ị. |