Thiết kế phản hồi lỗi API nhất quán với Problem Details
Dùng RFC 9457 để tạo lỗi API ổn định, chỉ rõ lỗi từng trường, giới hạn dữ liệu chẩn đoán và giữ hành vi phía gọi khi câu thông báo thay đổi.

Problem Details cung cấp một cấu trúc tiêu chuẩn cho phản hồi lỗi của HTTP API. Nếu đang xây dựng cả phía gọi lẫn máy chủ, bạn có thể dùng cấu trúc này để tách mã nhận diện lỗi dành cho phần mềm khỏi câu giải thích dành cho người đọc. Trường type nhận diện loại vấn đề, còn title và detail giải thích ở hai mức độ cụ thể khác nhau.
RFC 9457 định nghĩa định dạng và kiểu nội dung application/problem+json. Tiêu chuẩn không đưa ra một danh mục lỗi nghiệp vụ chung cho mọi ứng dụng. Bạn vẫn phải chọn lỗi nào cần mã nhận diện riêng và thông tin nào được phép cung cấp cho phía gọi.
Bắt đầu từ lỗi mà phía gọi phải sửa được
Giả sử biểu mẫu thanh toán gửi số lượng không hợp lệ và một cách giao hàng không được hỗ trợ. Yêu cầu là JSON hợp lệ, nhưng chỉ dẫn bên trong không thể được xử lý theo quy tắc kiểm tra của API. Phản hồi có thể như sau:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://shop.example/problems/invalid-order",
"title": "Dữ liệu đơn hàng không hợp lệ",
"status": 422,
"detail": "Sửa các trường được đánh dấu rồi gửi lại đơn hàng.",
"instance": "urn:request:checkout-418",
"errors": [
{"pointer":"/items/0/quantity","code":"positive_integer_required"},
{"pointer":"/delivery/method","code":"unsupported_delivery_method"}
]
}
URL và mã yêu cầu trong ví dụ chỉ dùng để minh họa. Thành viên errors là phần mở rộng được thiết kế riêng cho API này. Hai trường pointer và code không phải thành viên có sẵn của Problem Details; bạn cần mô tả ý nghĩa, quy tắc biểu diễn ký tự đặc biệt và cam kết ổn định của chúng.
Phía gọi có thể liên kết /items/0/quantity với ô số lượng của dòng hàng đầu tiên. Nó có thể chuyển positive_integer_required thành thông báo theo ngôn ngữ giao diện mà không phân tích câu tiếng Anh hoặc tiếng Việt trong detail. Nếu biểu mẫu thay đổi, một vùng báo lỗi chung vẫn cần hiển thị thông tin hữu ích khi pointer không còn tương ứng với trường đang nhìn thấy.
Chọn loại lỗi có ý nghĩa hẹp và ổn định
Một loại lỗi nên mô tả điều kiện có cách hiểu ổn định theo thời gian. invalid-order có thể đại diện cho nhóm lỗi kiểm tra dữ liệu đã được mô tả. something-went-wrong-v2 cho phía gọi rất ít thông tin và dễ trở thành nơi gom nhiều hành vi không liên quan.
RFC 9457 dùng một tham chiếu URI cho type. URL HTTP hữu ích khi dẫn tới tài liệu, nhưng phía gọi không nên phải tải trang đó đồng bộ mới xử lý được lỗi. Sự cố ở máy chủ tài liệu không nên ngăn trang thanh toán hiển thị thông báo kiểm tra dữ liệu. Nếu công cụ phát triển muốn hiển thị tài liệu, hãy tải và lưu đệm riêng.
Loại about:blank của tiêu chuẩn có nghĩa là vấn đề không mang thêm ngữ nghĩa ngoài mã trạng thái HTTP. Nó có thể phù hợp cho lỗi chung. Nếu phía gọi cần phân biệt lời mời đã hết hạn với lời mời đã được sử dụng, một loại lỗi cụ thể hoặc phần mở rộng có tài liệu sẽ hỗ trợ hành vi hữu ích hơn.
title là mô tả ngắn về loại vấn đề và thường giữ nguyên giữa các lần xảy ra, ngoại trừ việc dịch ngôn ngữ. detail giải thích lần xảy ra cụ thể. Đừng đưa mã giao dịch riêng vào tiêu đề khiến mỗi lỗi trông như một nhóm lỗi mới.
Mỗi lớp có đối tượng sử dụng riêng. Phần mềm HTTP dùng chung đọc mã trạng thái và kiểu nội dung. Ứng dụng đọc mã nhận diện vấn đề và trường mở rộng. Người dùng nhận lời giải thích hữu ích mà không thấy chi tiết nội bộ của máy chủ.
Giữ dòng trạng thái và nội dung phản hồi nhất quán
Thành viên status trong nội dung ghi lại mã HTTP gắn với vấn đề. Đôi khi một thành phần trung gian thay đổi mã của phản hồi, nên trường này có thể giữ lại ngữ cảnh hữu ích. Trong máy chủ do bạn kiểm soát, hãy sinh dòng trạng thái và giá trị trong nội dung từ cùng một bảng ánh xạ. Trả HTTP 200 nhưng đặt status: 422 trong JSON làm suy yếu hành vi của hệ thống giám sát, bộ nhớ đệm và phần mềm HTTP dùng chung.
Việc chọn 400 hay 422 cho một lỗi kiểm tra cụ thể thuộc hợp đồng API tổng thể. RFC 9110 định nghĩa ý nghĩa các mã đó. Problem Details không ghi đè định nghĩa và cũng không thay bạn đưa ra lựa chọn nghiệp vụ.
Phía gọi cần dung nạp thành viên mở rộng chưa biết. Việc thêm một liên kết chẩn đoán không nên làm hỏng phần mềm vốn tương thích. Tuy nhiên, điều đó không có nghĩa phải chấp nhận kiểu dữ liệu tùy ý cho trường đã biết. Nếu errors được mô tả là mảng, bên nhận cần xử lý phản hồi sai cấu trúc một cách an toàn, thay vì giả định mọi thành viên có thể được chèn trực tiếp thành HTML.
Tách dữ liệu chẩn đoán hữu ích khỏi thông tin nội bộ
Dấu vết ngăn xếp (stack trace) của cơ sở dữ liệu thường không phải nội dung detail phù hợp. Nó có thể lộ tên bảng, đường dẫn tệp nội bộ và chi tiết triển khai nhưng không cho phía gọi cách khắc phục. Hãy ánh xạ lỗi vi phạm tính duy nhất đã nhận diện sang vấn đề nghiệp vụ tương ứng. Ghi ngoại lệ nội bộ vào hệ thống hạn chế truy cập, rồi dùng mã tương quan để nối phản hồi công khai với bản ghi đó.
Bản thân mã tương quan cũng cần quy tắc. Tránh nhúng access token, địa chỉ email hoặc URL yêu cầu đầy đủ chứa tham số nhạy cảm. Nếu instance là URL có thể truy cập, hãy kiểm soát ai được xem nội dung của nó. Có trong tay một phản hồi lỗi không được đồng nghĩa với quyền xem trang chẩn đoán của tenant khác.
Với thao tác nhạy cảm về bảo mật, hãy cân nhắc liệu lỗi chi tiết có tiết lộ sự tồn tại của tài khoản hoặc tài nguyên hay không. Endpoint đặt lại mật khẩu có thể chủ động trả cùng kết quả công khai cho địa chỉ đã biết và chưa biết. Một cấu trúc JSON tiêu chuẩn không thể bù lại danh mục lỗi làm lộ thông tin.
Ánh xạ lỗi nội bộ tại một ranh giới được kiểm soát
Một bộ ánh xạ hữu ích bắt đầu từ danh mục lỗi được phép công khai. Giả sử cập nhật tài khoản vi phạm quy tắc duy nhất đã biết của slug hồ sơ. Bộ ánh xạ có thể trả về loại lỗi xung đột slug ổn định, kèm pointer tới trường nếu hợp đồng cần. Một ngoại lệ cơ sở dữ liệu chưa nhận diện nên đi theo nhánh lỗi nội bộ chung cho tới khi dịch vụ có cách ánh xạ đã được xem xét. Coi mọi ngoại lệ cơ sở dữ liệu là trùng slug sẽ báo sai nguyên nhân khi sự cố thật là mất kết nối.
const publicProblems = {
slug_conflict: {
status: 409,
type: 'https://shop.example/problems/slug-conflict',
title: 'Địa chỉ hồ sơ này đã được sử dụng'
}
};
function publicProblem(code, requestId) {
const known = Object.hasOwn(publicProblems, code) ? publicProblems[code] : undefined;
if (!known) {
return { status: 500, type: 'about:blank',
title: 'Lỗi máy chủ nội bộ', instance: 'urn:request:' + requestId };
}
return { ...known, instance: 'urn:request:' + requestId };
}
Đoạn mã nhận một phân loại nội bộ và mã yêu cầu an toàn; nó chủ động không nhận thông báo ngoại lệ thô để chép vào phản hồi. Trong hàm xử lý thật, chỉ tạo phân loại sau khi nhận diện đúng lỗi cụ thể. Kiểm tra định dạng mã yêu cầu trước khi dùng trong URI, đồng thời giữ toàn bộ ngoại lệ trong bản ghi chẩn đoán hạn chế truy cập được nối qua mã đó.
Hướng dẫn RESTful API của Zalando là một ví dụ về việc một công ty dùng biểu diễn vấn đề chung giữa các dịch vụ. Hướng dẫn như vậy có thể giúp phía gọi xử lý nhất quán; RFC 9457 mới là tiêu chuẩn định dạng được dùng trong bài này. Hãy kiểm tra phiên bản hiện tại của tài liệu công ty trước khi sao chép tham chiếu RFC cũ hoặc quy ước trường chỉ dành cho tổ chức đó.
Thay đổi hợp đồng lỗi có thể làm hỏng phía gọi dù phản hồi thành công vẫn giữ nguyên. Đổi errors thành violations, thay cú pháp pointer hoặc dùng lại một type cho điều kiện khác đều có thể phá cách biểu mẫu phục hồi. Giữ ý nghĩa type ổn định, cho phép phía gọi bỏ qua phần mở rộng bổ sung và quản lý phiên bản rõ ràng khi hành vi mới không tương thích.
Dịch ngôn ngữ là một lý do nữa để giữ nguyên hợp đồng cho phần mềm. detail tiếng Việt và detail tiếng Anh có thể mô tả cùng một loại vấn đề. Ngôn ngữ giải thích không được làm thay đổi cách phía gọi nhận diện slug trùng hoặc gắn lỗi vào trường. Kiểm thử hai bản thông báo với cùng hành vi phục hồi, đồng thời xác nhận văn bản được hiển thị dưới dạng văn bản an toàn thay vì được diễn giải thành HTML.
Kiểm thử lỗi chưa biết và trường hợp chỉ hiểu một phần
Kiểm thử một lỗi kiểm tra dữ liệu đã biết, một type chưa biết và một phản hồi không phải JSON từ proxy. Phía gọi cần cách xử lý dự phòng hữu ích cho cả ba. Trang lỗi HTML từ upstream không nên biến thành lỗi phân tích JSON rồi che mất sự cố ban đầu với người dùng.
Ở máy chủ, kiểm thử từng lỗi đã ánh xạ để bảo đảm đúng mã trạng thái, đúng type ổn định và không có nội dung ngoại lệ riêng tư. Cũng cần thử lỗi từng trường với danh sách rỗng, pointer ngoài dự kiến và nhiều lỗi trên một ô nhập. Các trường hợp này giúp phát hiện giả định sai trong phần hiển thị biểu mẫu.
Bắt đầu bằng triển khai nhỏ: một bộ ánh xạ loại lỗi công khai, một cấu trúc mở rộng có tài liệu cho lỗi từng trường và một nhánh dự phòng cho ngoại lệ ngoài dự kiến. Thêm loại vấn đề khi phía gọi có một hành động phục hồi riêng. Nhờ vậy, danh mục phản ánh hành vi thực tế thay vì sao chép mọi lớp ngoại lệ trong mã nguồn.