Thiết kế error response cho API thế nào cho tốt?

Bốn nguyên tắc chính:

• Format nhất quán toàn API: mọi endpoint trả lỗi cùng một cấu trúc để client viết một handler dùng chung — không chỗ trả { error }, chỗ trả { message }.
• Status code đúng ngữ nghĩa: 400 request sai, 401 chưa xác thực, 403 không đủ quyền, 404 không tồn tại, 409 xung đột trạng thái, 422 dữ liệu không hợp lệ, 429 quá rate limit, 5xx lỗi phía server. Đừng trả 200 kèm { "success": false } — phá cache, retry, monitoring dựa trên status code.
• Chuẩn có sẵn — RFC 9457 Problem Details: media type application/problem+json với các field type (URI định danh loại lỗi), title, status, detail, instance, cộng field mở rộng tùy ý (vd mảng errors cho lỗi validation từng field). Dùng chuẩn này thay vì tự thiết kế format riêng.
• Không lộ chi tiết nội bộ: stack trace, câu SQL, đường dẫn file, version thư viện trong response là tài liệu trinh sát cho kẻ tấn công. Trả thông điệp chung chung cho client + correlation/request id để đối chiếu log chi tiết phía server.

Thêm: message lỗi nên actionable — nói rõ sai ở đâu và cách sửa ("field email sai định dạng") thay vì "Bad Request" trống.