Khi nào API nên trả 401 và khi nào trả 403?

401 Unauthorized nghĩa là request thiếu xác thực hợp lệ: không có credential, token hết hạn, chữ ký sai. Tên của status gây hiểu nhầm, vì nó nói về danh tính chứ không phải quyền. Response nên có header WWW-Authenticate nêu rõ scheme như Bearer, và client có thể thử lại sau khi đăng nhập hoặc refresh.

403 Forbidden nghĩa là server biết bạn là ai, nhưng bạn không được phép làm việc này. Đăng nhập lại cũng không giải quyết được.

no token                  -> 401
expired token             -> 401
valid token, wrong role   -> 403
valid token, not owner    -> 403 (or 404)

Một vài điểm tinh tế:

• Trả 404 cho đối tượng mà người gọi thậm chí không nên biết là có tồn tại, để không xác nhận tài nguyên ở đó. Chọn một quy ước và áp dụng nhất quán.
• Dùng 400/422 cho đầu vào không hợp lệ và 429 cho rate limit, để mỗi mã lỗi chỉ có một nghĩa.
• Giữ thông báo chung chung. Đừng tiết lộ username có tồn tại không hoặc thiếu permission nào.

Điều cần nhớ: 401 hỏi "bạn là ai?", 403 trả lời "tôi biết bạn, và không được".