Mã lỗi

Cấu trúc response lỗi

{
  "statusCode": 400,
  "code": "INVALID_FILE_URL",
  "message": "fileUrl must use HTTPS",
  "data": null,
  "timestamp": "2026-05-15T10:00:00Z"
}

Trường	Mô tả
`statusCode`	HTTP status code
`code`	Mã lỗi ổn định — dùng để xử lý logic (xem lưu ý về lỗi `401` bên dưới)
`message`	Mô tả cho người đọc, có thể thay đổi giữa các phiên bản
`data`	Luôn `null` với response lỗi
`details`	Chỉ xuất hiện khi là mảng. Một số lỗi nghiệp vụ trả thêm mảng chi tiết; phần lớn lỗi không có trường này

Lỗi 401 giờ trả mã cụ thể trong trường code (API_KEY_INACTIVE, API_KEY_REVOKED, ORG_NOT_ACTIVE…), thay vì UNAUTHORIZED như các phiên bản trước. Rẽ nhánh theo code cho mọi lỗi 4xx, kể cả 401.Nếu tích hợp của bạn đang dựa vào message để đoán nguyên nhân 401, hãy chuyển sang đọc code — ổn định hơn và không đổi giữa các phiên bản.

400 — Dữ liệu đầu vào

Code	Nguyên nhân	Cách xử lý
`TENANT_DISABLED`	Không xác định được tổ chức (API Key sai hoặc tài khoản dịch vụ bị vô hiệu hoá)	Kiểm tra API Key, liên hệ quản trị viên
`INVALID_PROCESS_DEF`	`processDefCode` không tồn tại trong tổ chức	Đối chiếu mã quy trình đã được cấu hình
`INVALID_TEMPLATE_CODE`	`files[].templateCode` không tồn tại khi `source=template`	Kiểm tra mã mẫu tài liệu
`INVALID_FILE_URL`	`fileUrl` sai định dạng, không phải HTTPS, thiếu host, trỏ vào dải IP nội bộ, hoặc URL có redirect	Dùng URL HTTPS công khai, trỏ thẳng tới file, không qua redirect
`INVALID_SIGNER`	`signers[].stepCode` thiếu hoặc không khớp bước nào trong quy trình	Đối chiếu `stepCode` với cấu hình quy trình
`INVALID_SIGNER_USERNAME`	`signers[].username` không tồn tại hoặc không thuộc tổ chức của bạn	Kiểm tra username, hoặc dùng thông tin khách mời thay thế
`MISSING_ECM_CLASS_CODE`	Quy trình ký từ 2 loại tài liệu trở lên nhưng file không khai `ecmClassCode`	Gửi `ecmClassCode` cho từng file
`INVALID_REQUEST`	`fileUuid` thiếu, sai định dạng, hoặc trỏ vào hồ sơ thay vì file	Kiểm tra lại `fileUuid`
`TENANT_CODE_REQUIRED`	Dùng API Key toàn cục nhưng không gửi `tenantCode`	Gửi `tenantCode` ở query (GET) hoặc trong body (POST/PUT)
`TENANT_CODE_AMBIGUOUS`	`tenantCode` trùng ở nhiều tổ chức nên không xác định được tenant	Liên hệ quản trị viên đặt lại mã tổ chức cho duy nhất, hoặc dùng key theo tổ chức
`ORGANIZATION_CODE_AMBIGUOUS`	Mã đơn vị trùng ở nhiều bản ghi trong tenant	Liên hệ quản trị viên đặt lại mã đơn vị
`ROLE_CODE_AMBIGUOUS`	Mã vai trò trùng ở nhiều bản ghi trong tenant	Liên hệ quản trị viên đặt lại mã vai trò
`ROLE_AMBIGUOUS_IN_ORGANIZATION`	Nhiều vai trò trong cùng đơn vị khớp `roleCode` đã gửi	Định danh vai trò bằng `roleName` thay vì `roleCode`
`MEMBER_ROLE_REQUIRED`	Một dòng `members[]` không khai `roleCode` lẫn `roleName`	Gửi ít nhất một trong hai
`USER_CODE_DUPLICATED_IN_PAYLOAD`	Cùng một `code` xuất hiện nhiều lần trong một request đồng bộ hàng loạt	Gộp các dòng trùng lại trước khi gửi

401 — Xác thực

Thứ tự kiểm: bản thân API Key → tổ chức gắn với key → người dùng gắn với key. Gặp lỗi ở bước nào thì trả mã của bước đó.

Lỗi của API Key

Code	Nguyên nhân	Cách xử lý
`API_KEY_INVALID`	Key sai, không tồn tại hoặc sai định dạng	Kiểm tra lại chuỗi key
`API_KEY_INACTIVE`	Key đang bị tạm ngưng	Liên hệ quản trị viên bật lại — key cũ vẫn dùng được sau khi bật
`API_KEY_REVOKED`	Key đã bị thu hồi	Thu hồi là vĩnh viễn, phải xin cấp key mới
`API_KEY_EXPIRED`	Key đã quá hạn `expiresAt`	Xin cấp key mới hoặc gia hạn
`API_KEY_NOT_BOUND`	Key chưa gắn người dùng	Quản trị viên gán lại qua Admin UI → API Keys
`API_KEY_LEGACY_NOT_SUPPORTED`	Key kiểu cũ (lưu plaintext, không thu hồi hay xoay vòng được) gọi vào API Danh mục	Xin cấp key mới từ trình quản lý API Key

Lỗi của tổ chức gắn với key

Code	Nguyên nhân	Cách xử lý
`TENANT_DISABLED`	Key không gắn tổ chức nào	Liên hệ quản trị viên cấp lại key theo tổ chức
`ORG_NOT_FOUND`	Tổ chức đã bị xoá	Liên hệ quản trị viên
`ORG_NOT_ACTIVE`	Tổ chức đang ngừng hoạt động	Liên hệ quản trị viên kích hoạt lại tổ chức

Lỗi của người dùng gắn với key

Code	Nguyên nhân	Cách xử lý
`USER_NOT_FOUND`	Người dùng gắn với key đã bị xoá	Quản trị viên gán key cho người dùng khác
`USER_NOT_ACTIVE`	Người dùng bị vô hiệu hoá	Liên hệ quản trị viên kích hoạt lại
`USER_NOT_IN_ORG`	Người dùng không còn thuộc tổ chức của key	Quản trị viên thêm lại vào tổ chức, hoặc gán key cho người dùng khác

Không gửi header X-API-Key thì không nhận được 401 của API Key. Request rơi xuống tầng xác thực JWT và trả về 401 chung chung. Nếu gặp 401 khó hiểu, việc đầu tiên cần kiểm tra là header đã được gửi đi hay chưa (proxy hoặc API gateway có thể đã lược bỏ).

Xem thêm: Xác thực.

413 / 415 / 502 — Lỗi khi tải file từ `fileUrl`

Khi tạo hồ sơ với files[].source = "url", server tự tải file về. Các lỗi ở bước này có status riêng, không phải 400:

HTTP	Code	Nguyên nhân	Cách xử lý
`413`	`FILE_TOO_LARGE`	File vượt quá 50MB	Nén hoặc tách file
`415`	`UNSUPPORTED_FILE_TYPE`	Nội dung tải về không phải PDF	Kiểm tra file thật sự là PDF
`502`	`FILE_FETCH_FAILED`	Không phân giải được tên miền, máy chủ nguồn trả về mã khác `2xx`, hoặc quá thời gian chờ	Kiểm tra URL truy cập được công khai và phản hồi trong 30 giây

Hệ thống nhận diện PDF bằng chữ ký nhị phân đầu file, không dựa vào header Content-Type. File có Content-Type đúng nhưng nội dung không phải PDF vẫn bị từ chối với 415; ngược lại, file PDF hợp lệ phục vụ dưới application/octet-stream vẫn được chấp nhận.

403 — Không đúng phạm vi

Code	Nguyên nhân	Cách xử lý
`TENANT_CODE_MISMATCH`	Key gắn tổ chức A nhưng `tenantCode` chỉ tới tổ chức B	Bỏ `tenantCode`, hoặc gửi đúng mã tổ chức của key

404 — Không tìm thấy

Code	Nguyên nhân	Cách xử lý
`DOCUMENT_NOT_FOUND`	`documentId` không tồn tại trong tổ chức	Kiểm tra mã hồ sơ
`FILE_NOT_FOUND`	`fileUuid` không tồn tại hoặc thuộc tổ chức khác	Kiểm tra `fileUuid`
`TENANT_CODE_NOT_FOUND`	Không có tổ chức nào mang mã đó	Đối chiếu mã tổ chức với quản trị viên
`ORGANIZATION_CODE_NOT_FOUND`	`organizationCode` không có trong tenant	Lấy danh sách đơn vị qua API Danh mục
`ROLE_CODE_NOT_FOUND`	`roleCode` không có trong tenant	Lấy danh sách vai trò qua API Danh mục
`ROLE_NOT_FOUND_IN_ORGANIZATION`	Không vai trò nào trong đơn vị đó khớp `roleCode` / `roleName`	Đối chiếu tên vai trò của đúng đơn vị đó
`USER_CODE_NOT_FOUND`	Không có người dùng nào mang mã nhân sự đó trong tenant	Tạo mới bằng `POST /directory/users`, hoặc kiểm tra lại mã

FILE_NOT_FOUND gộp hai trường hợp “không tồn tại” và “thuộc tổ chức khác” một cách có chủ đích, để không lộ thông tin về dữ liệu của tổ chức khác.

409 — Xung đột

Code	Nguyên nhân	Cách xử lý
`DUPLICATE_DOCUMENT_ID`	`documentId` đã được dùng trong tổ chức	Đây là cơ chế idempotency. Nếu bạn đang thử lại một request có thể đã thành công, gọi `GET /documents/{documentId}` để lấy hồ sơ đã tạo
`USER_CODE_ALREADY_EXISTS`	Mã nhân sự đã thuộc về người khác trong tenant	Dùng `PUT /directory/users/{code}` để cập nhật thay vì tạo mới
`IDENTITY_IMMUTABLE`	Cố đổi `email` hoặc `username` của người dùng đã tồn tại	Hai trường này cố định sau khi tạo. Gửi lại đúng giá trị hiện tại, hoặc bỏ khỏi payload
`USERNAME_ALREADY_EXISTS`	Tên đăng nhập đã có trên hệ thống	Tên đăng nhập duy nhất trên toàn hệ thống, không chỉ trong tenant. Chọn giá trị khác
`EMAIL_ALREADY_EXISTS`	Email đã có trên hệ thống	Kiểm tra người đó đã có tài khoản chưa trước khi tạo mới

Tổng quan

Xác thực

Endpoints

Webhook

Mã lỗi

Cấu trúc response lỗi

400 — Dữ liệu đầu vào

401 — Xác thực

Lỗi của API Key

Lỗi của tổ chức gắn với key

Lỗi của người dùng gắn với key

413 / 415 / 502 — Lỗi khi tải file từ `fileUrl`

403 — Không đúng phạm vi

404 — Không tìm thấy

409 — Xung đột

​Cấu trúc response lỗi

​400 — Dữ liệu đầu vào

​401 — Xác thực

​Lỗi của API Key

​Lỗi của tổ chức gắn với key

​Lỗi của người dùng gắn với key

​413 / 415 / 502 — Lỗi khi tải file từ fileUrl

​403 — Không đúng phạm vi

​404 — Không tìm thấy

​409 — Xung đột

Cấu trúc response lỗi

400 — Dữ liệu đầu vào

401 — Xác thực

Lỗi của API Key

Lỗi của tổ chức gắn với key

Lỗi của người dùng gắn với key

413 / 415 / 502 — Lỗi khi tải file từ `fileUrl`

403 — Không đúng phạm vi

404 — Không tìm thấy

409 — Xung đột