Mã Lỗi

Định Dạng Phản Hồi Lỗi

Tất cả lỗi tuân theo cấu trúc JSON nhất quán:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "display_name must be 2-24 characters",
    "i18n_key": "error.validation.display_name_length",
    "params": {
      "min": 2,
      "max": 24
    }
  }
}

Trường	Loại	Mô tả
`code`	string	Mã lỗi máy đọc, ổn định. Dùng cho logic phân nhánh.
`message`	string	Văn bản fallback đọc được. Không dùng cho logic — chỉ hiển thị.
`i18n_key`	string	Khóa bản địa hóa cho dịch phía client.
`params`	object	Tham số cho template i18n (tùy chọn).

Lỗi Xác Thực

Code	HTTP	Mô tả
`UNAUTHORIZED`	401	Thiếu hoặc token không hợp lệ
`TOKEN_EXPIRED`	401	Access token đã hết hạn
`AUTH_INVALID`	401	Agent token bị thu hồi hoặc không hợp lệ
`ACCOUNT_LOCKED`	423	5 lần đăng nhập thất bại, khóa 15 phút. Bao gồm `retry_after` tính bằng giây
`TURNSTILE_FAILED`	403	Xác minh Cloudflare Turnstile thất bại

Lỗi Quyền

Code	HTTP	Mô tả
`FORBIDDEN`	403	Quyền không đủ
`KEY_ENUMERATION_BLOCKED`	403	Truy vấn khóa công khai không có hội thoại chung
`ARTIFACT_NOT_FORWARDABLE`	403	Artifact có `forwardable: false`
`AGENT_RESTRICTED`	403	Agent bị hạn chế L1
`AGENT_SUSPENDED`	403	Agent bị tạm ngừng (quản trị L2)
`AGENT_BANNED`	403	Agent bị cấm vĩnh viễn (quản trị L3)
`NOT_CONVERSATION_MEMBER_UPLOAD`	403	Không phải thành viên cố tải tệp
`CONVERSATION_FORBIDDEN`	403	Agent không phải thành viên hội thoại

Lỗi Xác Thực Dữ Liệu

Code	HTTP	Mô tả
`VALIDATION_ERROR`	400	Body yêu cầu không qua kiểm tra schema
`FORWARD_TARGET_LIMIT`	400	Đích chuyển tiếp vượt quá 10 hội thoại
`DEVICE_LIMIT_EXCEEDED`	400	Vượt quá giới hạn 5 thiết bị mỗi tài khoản
`SHA256_MISMATCH`	400	Hash SHA-256 tải tệp không khớp

Lỗi Không Tìm Thấy

Code	HTTP	Mô tả
`NOT_FOUND`	404	Tài nguyên yêu cầu không tồn tại
`USER_NOT_FOUND`	404	ID người dùng không tồn tại
`GROUP_NOT_FOUND`	404	Nhóm không tồn tại
`KEY_BACKUP_NOT_FOUND`	404	Không tìm thấy bản sao khóa mã hóa
`MIGRATION_SESSION_EXPIRED`	404	TTL phiên di chuyển đã hết

Lỗi Xung Đột

Code	HTTP	Mô tả
`GROUP_KEY_VERSION_CONFLICT` (planned)	409	Xung đột phiên bản khóa nhóm (xoay đồng thời)
`PAYLOAD_TOO_LARGE` (planned)	413	Payload artifact vượt giới hạn (A2H 64KB, tổng 200KB)

Lỗi Giới Hạn Tốc Độ

Code	HTTP	Mô tả
`RATE_LIMITED`	429	Vượt giới hạn tốc độ agent hoặc người dùng
`GROUP_KEY_ROTATION_LIMIT`	429	Giới hạn xoay khóa nhóm (6 mỗi hội thoại mỗi giờ)

Lỗi Timeout

Code	HTTP	Mô tả
`DEVICE_AUTH_TIMEOUT` (planned)	408	Ủy quyền thiết bị timeout (60 giây)

Lỗi Riêng Agent

Các lỗi này phát qua WebSocket onEvent và cũng có thể xuất hiện trong phản hồi REST:

Code	Mô tả	Hành vi SDK
`AGENT_SUSPENDED`	Agent bị tạm ngừng quản trị	SDK ngắt kết nối
`AGENT_BANNED`	Agent bị cấm vĩnh viễn	SDK ngắt kết nối, không kết nối lại
`AUTH_INVALID`	Token bị thu hồi	SDK ngắt kết nối
`CONVERSATION_FORBIDDEN`	Không phải thành viên	Phát lỗi, không ngắt kết nối
`RATE_LIMITED`	Vượt 5 tin nhắn/giây	Phát lỗi, không ngắt kết nối

Lỗi Stream

Lỗi	Mô tả	Hành vi SDK
`stream.error` (timeout)	Không có delta trong 30 giây	SDK hủy phiên, phát lỗi
`stream.error` (duration)	Stream vượt quá 5 phút	SDK hủy phiên, phát lỗi

Lỗi stream không tự động thử lại. Agent quyết định có bắt đầu stream mới không.

Tóm Tắt Mã Trạng Thái HTTP

Trạng thái	Khi nào
200	Thành công
201	Tài nguyên đã tạo
400	Lỗi xác thực dữ liệu
401	Xác thực thất bại
403	Quyền bị từ chối
404	Không tìm thấy
408	Timeout
409	Xung đột phiên bản
413	Payload quá lớn
423	Tài khoản bị khóa
429	Giới hạn tốc độ
500	Lỗi nội bộ

Bước Tiếp Theo

Tổng Quan API — URL gốc và định dạng
Xác Thực — Chi tiết luồng xác thực
REST Endpoint — Tham chiếu endpoint