Mã lỗi (Response Error Code)

Tài liệu này liệt kê mã code và message trong body response của các API xác thực (/v1/auth/*, /v1/attestation/*). Mã được ánh xạ từ internal/infrastructure/transport/grpc/{auth,identity,attestation}/result.go. Client phải xử lý theo code, không theo message.

1. Quy ước

Dải mã	Nhóm	Nguồn
0	Thành công	Tất cả
1000 - 1999	Attestation và session khởi tạo (init-session, get-challenge)	grpc/auth, grpc/attestation
2000 - 2999	Đăng ký, đăng nhập, OTP, social (/v1/auth/* còn lại)	grpc/identity

Mã không khớp với bảng nào sẽ trả 1999 (attestation, auth) hoặc 2999 (identity), kèm message “System error”.

2. Mã lỗi attestation và khởi tạo session

Code	Message	Ý nghĩa
1000	Invalid request	Request không hợp lệ
1001	Invalid certificate	Chứng chỉ client không hợp lệ
1002	Invalid userId	userId không đúng định dạng hex
1003	Session does not exist or has expired	Session không tồn tại hoặc đã hết hạn
1008	Invalid attestation	Dữ liệu attestation không hợp lệ
1009	Attestation verification failed	Xác minh attestation thất bại
1010	challengeJwt is invalid or has expired	challengeJwt không hợp lệ hoặc đã hết hạn (5 phút)
1999	System error	Lỗi hệ thống

3. Mã lỗi đăng ký, đăng nhập và OTP

3.1 Request và xác thực

Code	Message	Ý nghĩa
2000	Invalid request	Request không hợp lệ
2001	Invalid userId	userId không hợp lệ
2002	User is under 18 years old	Người dùng chưa đủ 18 tuổi
2003	Invalid step in authentication or registration flow	Gọi endpoint không đúng với nextStep hiện tại
2004	Authentication provider is not supported	Provider social không được hỗ trợ
2005	Session does not exist or has expired	Session không tồn tại hoặc đã hết hạn
2006	Invalid credentials	Thông tin đăng nhập không đúng
2007	Password mismatch	Mật khẩu không khớp
2008	Account is not verified	Tài khoản chưa được xác minh
2009	Account has been disabled	Tài khoản đã bị vô hiệu hóa
2010	Social account email is not verified	Email của tài khoản social chưa được xác minh
2011	Social nonce expired or already used	Nonce social đã hết hạn hoặc đã dùng
2012	Invalid token	Token không hợp lệ
2013	Invalid token audience	Audience của token không đúng
2014	Token has expired	Token đã hết hạn

3.2 OTP

Code	Message	Ý nghĩa
2015	OTP code not found	Không tìm thấy otpId
2016	OTP code invalid	OTP không đúng
2017	OTP code expired	OTP đã hết hạn (5 phút)
2018	OTP code max attempts reached	Đã nhập sai quá số lần cho phép

3.3 Trùng lặp tài nguyên

Code	Message	Ý nghĩa
2019	Email already exists	Email đã được đăng ký
2020	Phone number already exists	Số điện thoại đã tồn tại
2021	Phone number already registered	Số điện thoại đã thuộc tài khoản Justo khác (trả về ở verify-phone)
2022	Identity already linked to another account	Identity social đã liên kết với tài khoản khác

3.4 Không tìm thấy

Code	Message	Ý nghĩa
2023	User not found	Không tìm thấy người dùng
2024	User profile does not exist	Chưa có hồ sơ người dùng
2025	Identity not found	Không tìm thấy identity social

3.5 Hệ thống

Code	Message	Ý nghĩa
2999	System error	Lỗi hệ thống

4. Lưu ý khi xử lý lỗi

• Client xử lý theo code. message chỉ dùng để hiển thị hoặc ghi log.
• 2003 cho biết client đang gọi sai bước. Client cần đọc nextStep gần nhất và gọi đúng endpoint.
• 2015 đến 2018 áp dụng cho cả OTP email và OTP phone. Khi gặp 2017 hoặc 2018, client phải yêu cầu OTP mới ở bước trước đó.
• Chi tiết các bước xem Luồng xác thực. Mô hình dữ liệu xem DTO Authentication.