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

Với lỗi 401, code luôn là UNAUTHORIZED — không phải API_KEY_INVALID hay các mã cụ thể khác. Nguyên nhân chi tiết chỉ nằm trong message.Nghĩa là: với 4xx khác thì rẽ nhánh theo code; riêng 401 phải đọc message (hoặc đơn giản là coi mọi 401 là “thông tin xác thực có vấn đề” và kiểm tra lại API Key).

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`

401 — Xác thực

Mọi lỗi 401 đều trả code: "UNAUTHORIZED". Phân biệt nguyên nhân qua message:

`message` chứa	Nguyên nhân	Cách xử lý
API key không hợp lệ	Key sai, không tồn tại, sai định dạng, đã bị thu hồi, hoặc đã hết hạn	Kiểm tra key; nếu key từng chạy được thì nhiều khả năng đã bị thu hồi hoặc hết hạn — liên hệ quản trị viên
API key chưa gắn người dùng	Key chưa được bind userId	Quản trị viên gán lại qua Admin UI → API Keys → Edit
Tài khoản dịch vụ không hoạt động	User gắn với key đã bị vô hiệu hoá	Liên hệ quản trị viên kích hoạt lại

Key bị thu hồi và key hết hạn đều trả về cùng thông báo “API key không hợp lệ” — hệ thống không phân biệt hai trường hợp này ra ngoài. Đây là chủ đích để không lộ trạng thái key cho bên gọi không hợp lệ.

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.

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`

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

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

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

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

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

​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

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

404 — Không tìm thấy

409 — Xung đột