TL;DR
RFC 9457 (Thông tin chi tiết lỗi cho API HTTP) là định dạng chuẩn cho các phản hồi lỗi của API. Nó thay thế các định dạng lỗi tùy chỉnh bằng một cấu trúc nhất quán: loại, tiêu đề, trạng thái, chi tiết và thể hiện. Modern PetstoreAPI triển khai RFC 9457 trên tất cả các phản hồi lỗi với thỏa thuận nội dung và chi tiết xác thực phù hợp.
Giới thiệu
API của bạn trả về một lỗi. Phản hồi trông như thế nào? Nếu bạn giống như hầu hết các API, bạn đã tự tạo định dạng riêng cho mình:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Mỗi API có một định dạng lỗi khác nhau. Các client cần xử lý lỗi tùy chỉnh cho từng API. Không có cách chuẩn để phân tích cú pháp lỗi, hiển thị chúng cho người dùng hoặc ghi nhật ký để gỡ lỗi.
RFC 9457 giải quyết vấn đề này. Đây là một tiêu chuẩn của IETF định nghĩa cách các API nên trả về lỗi. Thay vì tự tạo định dạng riêng, bạn sử dụng một tiêu chuẩn đã được chứng minh mà các client đã hiểu.
Swagger Petstore cũ đã sử dụng các định dạng lỗi tùy chỉnh không có sự nhất quán. Modern PetstoreAPI triển khai RFC 9457 trên tất cả các phản hồi lỗi, cung cấp chi tiết lỗi có cấu trúc, có thể đọc được bằng máy.
Trong hướng dẫn này, bạn sẽ tìm hiểu RFC 9457 là gì, cách triển khai nó một cách chính xác và cách Modern PetstoreAPI sử dụng nó cho tất cả các phản hồi lỗi.
Vấn đề lỗi API
Trước RFC 9457, mỗi API đều tự tạo định dạng lỗi riêng cho mình.
Các biến thể định dạng lỗi phổ biến
Định dạng 1: Thông báo đơn giản
{"error": "User not found"}
Định dạng 2: Mã và thông báo
{"code": "USER_NOT_FOUND", "message": "User not found"}
Định dạng 3: Cấu trúc lồng nhau
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Định dạng 4: Mảng lỗi
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Các vấn đề với định dạng tùy chỉnh
1. Không nhất quán: Các client cần phân tích cú pháp tùy chỉnh cho mỗi API.
2. Thiếu thông tin: Một số định dạng thiếu mã lỗi, một số thiếu chi tiết, một số thiếu cả hai.
3. Không có cấu trúc đọc được bằng máy: Khó xử lý lỗi bằng lập trình.
4. Quốc tế hóa kém: Thông báo lỗi được mã hóa cứng bằng tiếng Anh.
5. Không có tiêu chuẩn cho lỗi xác thực: Mỗi API xử lý lỗi cấp trường khác nhau.
RFC 9457 là gì?
RFC 9457 (được xuất bản tháng 7 năm 2023) định nghĩa “Thông tin chi tiết lỗi cho API HTTP”. Đây là một tiêu chuẩn IETF chỉ định cách các API nên cấu trúc phản hồi lỗi.
Các tính năng chính
Kiểu phương tiện tiêu chuẩn: application/problem+json (hoặc application/problem+xml)
Cấu trúc nhất quán: Tất cả các lỗi đều theo cùng một định dạng
Có thể đọc được bằng máy: Các client có thể phân tích cú pháp lỗi bằng lập trình
Có thể mở rộng: Bạn có thể thêm các trường tùy chỉnh trong khi vẫn duy trì khả năng tương thích
Nhận biết HTTP: Tích hợp với mã trạng thái HTTP
RFC 9457 so với lỗi tùy chỉnh
Lỗi tùy chỉnh:
{"error": "Email is required"}
Lỗi RFC 9457:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
Phiên bản RFC 9457 cung cấp:
- URL loại lỗi cho tài liệu
- Tiêu đề dễ đọc
- Mã trạng thái HTTP
- Giải thích chi tiết
- Đường dẫn yêu cầu gây ra lỗi
- Chi tiết xác thực cấp trường
Giải thích cấu trúc RFC 9457
RFC 9457 định nghĩa năm trường tiêu chuẩn và cho phép mở rộng tùy chỉnh.
Các trường tiêu chuẩn
1. type (chuỗi, bắt buộc)
Một tham chiếu URI xác định loại lỗi. Nên trỏ đến tài liệu dễ đọc.
"type": "https://petstoreapi.com/errors/validation-error"
Nếu bỏ qua, mặc định là about:blank.
2. title (chuỗi, bắt buộc)
Một tóm tắt ngắn gọn, dễ đọc về loại lỗi. Không nên thay đổi giữa các lần xuất hiện.
"title": "Validation Error"
3. status (số, bắt buộc)
Mã trạng thái HTTP. Bao gồm để tiện lợi để các client không cần phân tích cú pháp tiêu đề.
"status": 400
4. detail (chuỗi, tùy chọn)
Một giải thích dễ đọc cụ thể cho lần xuất hiện lỗi này.
"detail": "The email field must be a valid email address"
5. instance (chuỗi, tùy chọn)
Một tham chiếu URI xác định lần xuất hiện cụ thể của lỗi. Thường là đường dẫn yêu cầu.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Các phần mở rộng tùy chỉnh
Bạn có thể thêm các trường tùy chỉnh để cung cấp thêm ngữ cảnh:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Cách Modern PetstoreAPI triển khai RFC 9457
Modern PetstoreAPI sử dụng RFC 9457 cho tất cả các phản hồi lỗi.
Ví dụ 1: Không tìm thấy tài nguyên
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
Ví dụ 2: Lỗi xác thực
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
Ví dụ 3: Vượt quá giới hạn tỷ lệ
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Xem tài liệu xử lý lỗi của Modern PetstoreAPI để biết tất cả các loại lỗi.
Lỗi xác thực với RFC 9457
Lỗi xác thực cần chi tiết cấp trường. RFC 9457 cho phép các phần mở rộng tùy chỉnh cho điều này.
Định dạng xác thực của Modern PetstoreAPI
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Các điểm chính
mảng errors: Chứa chi tiết xác thực cấp trường
field: Đường dẫn JSON đến trường không hợp lệ
message: Thông báo lỗi dễ đọc
code: Mã lỗi có thể đọc được bằng máy
rejectedValue: Giá trị bị từ chối (tùy chọn)
Định dạng này cho phép các client:
- Hiển thị lỗi cấp trường trong biểu mẫu
- Tô sáng các trường không hợp lệ
- Cung cấp thông báo lỗi cụ thể
- Xử lý lỗi bằng lập trình
Kiểm thử phản hồi lỗi với Apidog
Apidog giúp bạn kiểm tra sự tuân thủ RFC 9457.
Trường hợp kiểm thử: Lỗi xác thực
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Trường hợp kiểm thử: URL loại lỗi
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Chuyển đổi từ định dạng lỗi tùy chỉnh
Nếu bạn đang sử dụng các định dạng lỗi tùy chỉnh, đây là cách để chuyển đổi sang RFC 9457.
Bước 1: Thêm tiêu đề Content-Type
Bắt đầu trả về application/problem+json:
Content-Type: application/problem+json
Bước 2: Ánh xạ các trường hiện có
Ánh xạ định dạng tùy chỉnh của bạn sang RFC 9457:
Trước đây:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Sau đây:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Bước 3: Hỗ trợ cả hai định dạng (Giai đoạn chuyển tiếp)
Sử dụng thương lượng nội dung để hỗ trợ cả hai định dạng:
Accept: application/json → Returns custom format
Accept: application/problem+json → Returns RFC 9457 format
Bước 4: Loại bỏ định dạng tùy chỉnh
Sau khi các client đã chuyển đổi, hãy loại bỏ định dạng tùy chỉnh và trả về RFC 9457 theo mặc định.
Kết luận
RFC 9457 cung cấp một định dạng tiêu chuẩn cho các phản hồi lỗi API. Nó thay thế các định dạng lỗi tùy chỉnh bằng một cấu trúc nhất quán, có thể đọc được bằng máy mà các client có thể phân tích cú pháp bằng lập trình.
Modern PetstoreAPI triển khai RFC 9457 trên tất cả các phản hồi lỗi, minh họa cách cấu trúc lỗi đúng cách với chi tiết xác thực phù hợp, URL loại lỗi và mã trạng thái HTTP.
Sử dụng Apidog để kiểm tra sự tuân thủ RFC 9457, xác thực cấu trúc lỗi và đảm bảo API của bạn trả về các phản hồi lỗi phù hợp.
Câu hỏi thường gặp
RFC 9457 có bắt buộc đối với API REST không?
Không, nhưng đây là tiêu chuẩn được khuyến nghị. Việc sử dụng RFC 9457 giúp API của bạn nhất quán hơn và dễ tích hợp hơn cho các client.
Tôi có thể sử dụng RFC 9457 với XML không?
Có, RFC 9457 định nghĩa cả hai định dạng JSON (application/problem+json) và XML (application/problem+xml).
Tôi có nên luôn bao gồm tất cả năm trường tiêu chuẩn không?
type, title và status là bắt buộc. detail và instance là tùy chọn nhưng được khuyến nghị để có ngữ cảnh lỗi tốt hơn.
Tôi có thể thêm các trường tùy chỉnh vào phản hồi RFC 9457 không?
Có, RFC 9457 có khả năng mở rộng. Bạn có thể thêm các trường tùy chỉnh như errors, retryAfter hoặc traceId để có thêm ngữ cảnh.
Tôi xử lý lỗi xác thực với RFC 9457 như thế nào?
Thêm một mảng errors tùy chỉnh với chi tiết cấp trường. Modern PetstoreAPI minh họa mẫu này trong các phản hồi lỗi xác thực của nó.
URL loại lỗi nên trỏ đến đâu?
Nó nên trỏ đến tài liệu dễ đọc giải thích loại lỗi, các nguyên nhân có thể và cách khắc phục.
Tôi có cần thay đổi mã trạng thái HTTP khi sử dụng RFC 9457 không?
Không, RFC 9457 hoạt động với các mã trạng thái HTTP tiêu chuẩn. Trường status trong phản hồi phải khớp với mã trạng thái HTTP.
Tôi kiểm tra sự tuân thủ RFC 9457 như thế nào?
Sử dụng Apidog để xác thực cấu trúc phản hồi lỗi, kiểm tra các trường bắt buộc và xác minh kiểu nội dung khớp với các thông số kỹ thuật của RFC 9457.