Danh mục lỗi — GIW POC Identity Platform

Trạng thái: POC · Ngày: 21/09/2026

1. Mô hình lỗi chuẩn

Mọi API tự xây đều trả về cùng một hình dạng khi thất bại:

{
  "code": "EMPLOYEE_VERIFICATION_FAILED",
  "message": "Unable to verify employee information",
  "correlationId": "corr-9b1f2c7e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "timestamp": "2026-09-21T04:30:00.000Z"
}

Quy tắc:

  • code ổn định và máy đọc được. Client rẽ nhánh theo nó, không bao giờ theo message.
  • message dành cho người đọc log. Nó cố ý mơ hồ về lý do một lượt kiểm tra danh tính thất bại.
  • correlationId luôn có mặt và luôn khớp với header response X-Correlation-ID.
  • Không body lỗi nào được chứa CCCD, token, mật khẩu hay stack trace.

2. Danh mục

Code HTTP Do ai phát Nghĩa là gì Client nên làm gì
INVALID_REQUEST 400 tất cả JSON sai định dạng, thiếu trường, hoặc một trường không khớp pattern Sửa request; đừng gửi lại y nguyên
UNAUTHORIZED 401 tất cả Thiếu credential, sai định dạng, hết hạn hoặc không tin cậy Xác thực lại
FORBIDDEN 403 Entitlement Credential hợp lệ nhưng request không được phép — ví dụ subjectId trong body mâu thuẫn với token Đừng thử lại; đây là bug hoặc một cuộc tấn công
NOT_FOUND 404 tất cả Không có endpoint hoặc tài nguyên đó —
EMPLOYEE_VERIFICATION_FAILED 401 (render lại form) Authenticator Mã nhân viên và CCCD không khớp bản ghi nào. Giống hệt nhau cho "không có mã này" và "sai CCCD". Cho người dùng thử lại, trong giới hạn số lần
EMPLOYEE_INACTIVE 401 (render lại form) Authenticator / HR Khớp bản ghi nhưng nhân viên không ở trạng thái ACTIVE Hướng người dùng liên hệ nhân sự, không phải thử lại
HR_SERVICE_TIMEOUT 504 → trang 503 HR / Authenticator HR không trả lời trong thời gian chờ, kể cả sau khi thử lại Chờ rồi thử lại sau. Tuyệt đối không quay sang cấp quyền.
HR_SERVICE_UNAVAILABLE 503 HR / Authenticator HR trả 5xx, không kết nối được, hoặc từ chối credential của service Chờ; báo vận hành
IDENTITY_LINK_CONFLICT 409 Authenticator Nhiều hơn một user Keycloak cùng mang employee_ref này Dừng lại. Phải sửa dữ liệu thủ công.
ENTITLEMENT_DENIED 403 · 422 Entitlement · Session 403: subject không đủ điều kiện. 422: gọi grant mà không có entitlementId. Hiển thị lý do; đừng gửi lại cùng một request
SESSION_NOT_FOUND 404 Session Không có session với id đó Tạo session mới
SESSION_EXPIRED 409 Session Session đang ở trạng thái REVOKED hoặc EXPIRED, không grant được Tạo session mới
RATE_LIMITED 429 HR Quá nhiều lần xác minh thất bại trên cùng một hồ sơ nhân viên, hoặc chạm trần toàn cục. Lần xác minh thành công không bao giờ bị tính Chờ khoảng 60 s. Đừng thử lại ngay — thử lại chỉ làm hàng đợi tệ hơn
DMN_UNAVAILABLE 503 Entitlement Bộ máy quyết định không trả lời. Fail closed: một bộ máy không trả lời được thì không phải là câu trả lời "không" Chờ; báo vận hành
DMN_EVALUATION_ERROR 422 DMN Model nạp được nhưng không đánh giá được — lỗi mô hình hoá, không phải một lần từ chối Sửa file .dmn; đừng coi là bị từ chối
MODEL_NOT_FOUND 404 DMN Không có decision model nào tên đó Kiểm tra GET /api/v1/decisions
INTERNAL_ERROR 500 tất cả Lỗi server chưa được xử lý Thử lại một lần, rồi báo động

3. Lý do từ chối kèm ENTITLEMENT_DENIED

Body 403 mang thêm trường reason:

reason Nghĩa là gì
EMPLOYEE_NOT_VERIFIED Token khai user_type=EMPLOYEE nhưng không mang employee_verified=true. Lẽ ra không bao giờ chạm tới; nếu nó bắn ra thì ánh xạ claim đang hỏng.
COMPANY_NOT_ELIGIBLE Công ty không nằm trong EMPLOYEE_COMPANIES. Minh hoạ bằng nhân viên test PTX10001 (PARTNER-X).
UNKNOWN_USER_TYPE Có user_type nhưng không nhận ra. Thiếu user_type thì không phải lỗi — nó được coi là CUSTOMER.

4. Thông báo hiển thị cho người dùng

Authenticator trả về key của thông báo, được bộ message của theme dịch sang tiếng Việt và tiếng Anh.

Key Tiếng Việt English
employeeVerifyFailed Không xác minh được thông tin. Vui lòng kiểm tra lại mã nhân viên và số CCCD. We could not verify those details.
employeeVerifyMissingFields Vui lòng nhập đủ hai ô. Please fill in both fields.
employeeVerifyInvalidFormat Vui lòng kiểm tra định dạng thông tin đã nhập. Please check the format of the details you entered.
employeeVerifyInactive Hồ sơ nhân viên không ở trạng thái hoạt động. Vui lòng liên hệ nhân sự. This employee record is not active.
employeeVerifyNotEligible Hồ sơ này không thuộc diện dùng Wi-Fi trên tàu bay. This employee record is not eligible for onboard Wi-Fi.
employeeVerifyHrTimeout Hệ thống nhân sự phản hồi chậm. Vui lòng thử lại. The HR system did not respond in time.
employeeVerifyHrUnavailable Hệ thống nhân sự tạm thời không truy cập được. The HR system is unavailable.
employeeVerifyRateLimited Thử quá nhiều lần. Vui lòng bắt đầu lại. Too many attempts. Please start again.
employeeLinkConflict Tìm thấy nhiều hồ sơ trùng cho nhân viên này. Vui lòng liên hệ hỗ trợ. We found more than one record for this employee.

Lưu ý employeeVerifyFailed cố ý không nói ô nào sai.

5. Những gì tuyệt đối không được xuất hiện trong lỗi

Cấm Vì sao
Số CCCD, đầy đủ hay một phần Dữ liệu cá nhân nhạy cảm
Bất kỳ sự phân biệt nào giữa "không có nhân viên này" và "sai CCCD" Dò tìm danh sách (enumeration)
Token, khoá hay mật khẩu Lộ credential
Stack trace hoặc tên host nội bộ Do thám hệ thống
Response gốc của HR Nguyên tắc lộ tối thiểu
Việc credential gọi HR có bị từ chối hay không Một 401 từ HR hiện ra với người dùng là "tạm thời không truy cập được"

GIW POC Identity Platform · bản demo local · không phải production · sinh từ repository