Trả lỗi API để phía sử dụng biết cách xử lý

Lỗi API cần giúp phía gọi quyết định bước tiếp theo. Thông báo thất bại chung chung có thể gây thử lại mù quáng, phát sinh yêu cầu hỗ trợ không cần thiết hoặc khiến giao diện đổ lỗi cho người dùng. Hãy bắt đầu thiết kế lỗi từ quyết định của phía sử dụng, không phải danh sách ngoại lệ máy chủ.

Cho phần mềm một tín hiệu ổn định

RFC 9457 định nghĩa problem details để truyền thông tin lỗi mà máy có thể đọc trong phản hồi HTTP.[3] Định dạng có các thành phần như type, title, status, detail và instance.[3] Dùng loại lỗi ổn định để nhận diện một tình huống có tài liệu. Coi phần detail là lời giải thích cho con người, không phải mã mà phía gọi phải phân tích chuỗi.

Chọn mã trạng thái của phản hồi HTTP thực tế theo kết quả HTTP. Nếu thêm thành phần status trong nội dung lỗi, giữ nó nhất quán với phản hồi đó. Đừng giấu thao tác thất bại trong phản hồi thành công chỉ để đơn giản hóa mã kết nối phía gọi. Mô tả riêng kết quả từng phần nếu thao tác có hỗ trợ.

Giải thích bước tiếp theo, không phỏng đoán

Nên xây danh mục lỗi nhỏ theo hướng khôi phục. Lỗi kiểm tra trường phải chỉ ra dữ liệu bị ảnh hưởng và quy tắc sửa. Lỗi quyền truy cập nên hướng người dùng đến quy trình cấp quyền phù hợp, nhưng không tiết lộ tài nguyên của khách hàng khác.

Một lỗi tạm thời không tự cho phép lặp lại thao tác nghiệp vụ. Yêu cầu gốc có thể đã hoàn tất trước khi phản hồi gặp lỗi. Liên kết hướng dẫn thử lại với hợp đồng idempotency hoặc tra cứu trạng thái của thao tác. Với công việc bất đồng bộ, phân biệt việc không tra cứu được trạng thái với bản thân công việc nghiệp vụ thất bại. Như vậy, quan sát kỹ thuật không biến thành kết luận nghiệp vụ sai.

Tách câu chữ hiển thị cho người dùng khỏi mã nhận diện lỗi ổn định. Nhờ vậy, các nhóm có thể dịch lời giải thích sang ngôn ngữ khác mà không đổi tình huống mà phần mềm phía gọi nhận biết và xử lý.

Duyệt đồng thời tính an toàn và khả năng sử dụng

RFC 9457 cảnh báo rằng problem details không phải công cụ gỡ lỗi triển khai và nêu rủi ro lộ chi tiết nội bộ.[3] Giữ vết ngăn xếp, thông tin xác thực, câu lệnh cơ sở dữ liệu và nội dung riêng tư trong hệ thống chẩn đoán có kiểm soát, không đưa vào lỗi công khai. Thay vào đó, cấp mã liên hệ chẩn đoán an toàn cho hỗ trợ.

• Định nghĩa loại ổn định và người phụ trách cho mỗi tình huống lỗi dự kiến.
• Chỉ rõ vị trí trường lỗi và quy tắc sửa có thể thực hiện.
• Quy định khi nào sửa dữ liệu, xác thực, chờ, tra cứu hay gọi hỗ trợ.
• Kiểm thử loại lỗi chưa biết để phía gọi vẫn dừng theo cách an toàn.

Ví dụ giả định: duyệt mua hàng

Ví dụ giả định: công cụ mua hàng từ chối phê duyệt vì yêu cầu thiếu trung tâm chi phí. Phản hồi nêu tên trường và định dạng chấp nhận. Giao diện đánh dấu trường đó và giữ nguyên phần còn lại của biểu mẫu.

Nếu dịch vụ phê duyệt mất khả dụng sau khi gửi, giao diện hiển thị trạng thái chưa rõ và cho phép tra cứu. Giao diện không yêu cầu người dùng lập tức gửi thêm phê duyệt. Việc duy trì danh mục lỗi cần phối hợp khi các tình huống thay đổi. Hãy bắt đầu từ lỗi đang khiến người dùng không biết phải làm gì, rồi kiểm tra xem người chưa quen API có chọn đúng bước tiếp theo hay không.