Tham Khảo Mã Trạng Thái HTTP

Tài liệu Tham khảo Mã Trạng Thái HTTP là một danh mục hoàn chỉnh, có thể tìm kiếm của mọi mã trạng thái được định nghĩa trong các thông số kỹ thuật HTTP — từ 100 Continue cho đến 511 Network Authentication Required. Mỗi mục hiển thị tên chuẩn tắc, RFC định nghĩa mã đó, ý nghĩa thực sự của mã là gì, khi nào nên gửi, khi nào không nên gửi, và các lỗi thường gặp làm ảnh hưởng đến các cơ sở mã nguồn trong thực tế. Bộ lọc trực tiếp và các thẻ phân loại giúp bạn chuyển từ lớp này sang lớp khác chỉ với một cú nhấp chuột.

Không giống như một bảng tra cứu thông tin phẳng thông thường, công cụ này cung cấp cho mỗi mã một trang vi mô riêng với ba bảng màu được mã hóa (nên dùng / không nên dùng / lỗi thường gặp) cùng các trình xử lý có sẵn để sao chép cho Express.js, Django, FastAPI, và Go net/http. Sơ đồ đường truyền động hiển thị hành trình yêu cầu từ máy khách đến máy chủ và mã trạng thái được chọn truyền ngược lại — rất hữu ích cho những người mới bắt đầu tìm hiểu về những gì mã trạng thái thực sự đại diện trên đường truyền.

Tại sao một tài liệu tham khảo mã trạng thái lại quan trọng

Cách sử dụng Tài liệu Tham khảo Mã Trạng Thái HTTP

1. Tra cứu nhanh. Nhập một số mã (404) hoặc một phần tên (teapot, gateway) vào hộp tìm kiếm ở trên cùng rồi gửi. Mục khớp từ khóa sẽ mở ra với bảng chi tiết đầy đủ.
2. Duyệt theo lớp mã. Nhấp vào bất kỳ thẻ nào trong 5 thẻ phân loại (1xx, 2xx, 3xx, 4xx, 5xx) để lọc lưới thẻ theo lớp đó. Nhấp vào Tất cả để đặt lại.
3. Bộ lọc trực tiếp. Hộp lọc ngay phía trên lưới thẻ sẽ thu hẹp các thẻ khi bạn nhập — hữu ích khi bạn chỉ nhớ một nửa tên như too many hoặc precondition.
4. Kiểm tra một mã. Nhấp vào bất kỳ thẻ nào để mở bảng chi tiết của mã đó. Bạn sẽ thấy ý nghĩa, khi nào nên dùng, khi nào không nên dùng, các lỗi thường gặp và một khối đoạn mã cho 4 framework.
5. Sao chép một đoạn mã. Sử dụng trình chuyển đổi tab và nút Sao chép nhỏ để lấy trình xử lý có sẵn để dán.
6. So sánh các mã lân cận. Bảng chi tiết kết thúc bằng các thẻ anh em cùng lớp mã (1xx / 2xx / 3xx / 4xx / 5xx) để so sánh song song một cách nhanh chóng.

Năm lớp trạng thái HTTP sơ lược

Các cặp mã thường bị nhầm lẫn

• 401 so với 403. 401 có nghĩa là chưa xác thực — yêu cầu thiếu thông tin đăng nhập hợp lệ. 403 có nghĩa là đã xác thực nhưng không được phép — thông tin đăng nhập hoàn toàn ổn nhưng người dùng không có quyền truy cập.
• 404 so với 410. 404 có nghĩa là không xác định: có thể nó tồn tại ở đâu đó, hoặc có thể do lỗi chính tả. 410 có nghĩa là chủ động xóa bỏ: các công cụ tìm kiếm nên gỡ bỏ nó khỏi danh mục chỉ mục.
• 301 so với 302 so với 307 so với 308. 301 / 308 là vĩnh viễn (308 bảo lưu nghiêm ngặt phương thức & nội dung), 302 / 307 là tạm thời (307 bảo lưu nghiêm ngặt phương thức & nội dung). Hãy sử dụng 307 / 308 cho các chuyển hướng POST / PUT / PATCH.
• 400 so với 422. 400 có nghĩa là nội dung yêu cầu không đúng định dạng (sai JSON, thiếu trường dữ liệu). 422 có nghĩa là nội dung được phân tích cú pháp thành công nhưng các giá trị không vượt qua được các quy tắc nghiệp vụ (định dạng email không hợp lệ, số lượng vượt quá phạm vi).
• 502 so với 503 so với 504. 502 có nghĩa là máy chủ tuyến trên gửi dữ liệu rác. 503 có nghĩa là máy chủ đang bị quá tải hoặc đang bảo trì. 504 có nghĩa là máy chủ tuyến trên không phản hồi kịp thời.
• 409 so với 412. 409 là một sự xung đột với trạng thái hiện tại của tài nguyên. 412 có nghĩa cụ thể là một tiêu đề điều kiện tiên quyết (If-Match, If-Unmodified-Since) được đánh giá là sai.

Các tiêu đề đi kèm với các mã trạng thái cụ thể

• 201 Created — nên bao gồm tiêu đề Location trỏ tới tài nguyên mới.
• 301 / 302 / 307 / 308 — phải bao gồm tiêu đề Location chứa URL đích.
• 304 Not Modified — phải phản hồi lại các tiêu đề đáng lẽ sẽ xuất hiện trên mã 200 (ETag, Cache-Control, Vary).
• 401 Unauthorized — phải bao gồm tiêu đề WWW-Authenticate liệt kê các phương thức được chấp nhận (Basic, Bearer).
• 405 Method Not Allowed — phải bao gồm tiêu đề Allow liệt kê các phương thức được phép sử dụng.
• 413 / 429 / 503 — thường bao gồm Retry-After (số giây hoặc định dạng ngày HTTP) để máy khách lùi thời gian yêu cầu lại một cách chính xác.
• 416 Range Not Satisfiable — phải bao gồm tiêu đề Content-Range: bytes */<length>.

Các mã trạng thái bạn hầu như luôn có thể bỏ qua

Một vài mã trạng thái hợp lệ về mặt kỹ thuật nhưng cực kỳ hiếm gặp trong các API hiện đại: 305 Use Proxy (đã ngừng sử dụng), 306 (được đặt trước, không sử dụng), 305, 506 Variant Also Negotiates, 510 Not Extended, và 508 Loop Detected. Hầu hết được giữ lại trong danh mục đăng ký vì lý do lịch sử. Nếu thư viện hoặc phần mềm trung gian (middleware) của bạn phát ra một trong số các mã đó, hãy coi đó là một báo cáo lỗi đối với thư viện — chứ không phải là một gợi ý để xử lý nó một cách đặc biệt.

Câu hỏi thường gặp

Công cụ này có bao gồm các mã từ các RFC khác ngoài 9110 không?

Có. Nó bao gồm RFC 9110 (ngữ nghĩa HTTP), RFC 6585 (bổ sung 4xx / 5xx), RFC 4918 (WebDAV), RFC 5842 (WebDAV bindings), RFC 7725 (451), RFC 8297 (103 Early Hints), RFC 8470 (425 Too Early), và tài liệu mang tính chất vui nhộn nổi tiếng RFC 2324 (418 Teapot).

Các mã này có hợp lệ trong HTTP/2 và HTTP/3 không?

Có. Ý nghĩa của mã trạng thái được định nghĩa trong RFC 9110, đây là tài liệu về ý nghĩa HTTP độc lập với phiên bản. HTTP/2 (RFC 9113) và HTTP/3 (RFC 9114) chỉ thay đổi cách đóng khung và truyền tải.

Tôi có thể liên kết trực tiếp đến một mã cụ thể không?

Hãy gửi biểu mẫu với một mã duy nhất (ví dụ 404) và bảng chi tiết sẽ tải ở bên dưới biểu mẫu. URL hiển thị tìm kiếm của bạn và an toàn để chia sẻ — khi mở nó ra sẽ tải cùng một kết quả tương tự.

Tại sao framework của tôi không cho phép tôi trả về mã 418?

Các phiên bản cũ của một số thư viện HTTP từ chối phát ra các mã không nằm trong danh mục đăng ký nội bộ của chúng. Cách khắc phục là nâng cấp thư viện hoặc, nếu có thể, tự viết dòng trạng thái theo cách thủ công.

Một API có bao giờ nên trả về mã 200 với nội dung lỗi không?

Không. Các hệ thống giám sát, cơ chế thử lại và các bên trung gian đều giả định rằng 2xx có nghĩa là thành công. Nếu bạn phải trả về cấu trúc lỗi, hãy trả về một mã 4xx hoặc 5xx phù hợp và đặt chi tiết cấu trúc lỗi bên trong nội dung phản hồi. Định dạng Problem Details cho HTTP APIs (RFC 9457) là một khuôn mẫu tốt.

Có danh mục đăng ký chính thức nào cho các mã trạng thái HTTP không?

Có. IANA duy trì danh mục đăng ký tại iana.org/assignments/http-status-codes. Công cụ này luôn đồng bộ với danh mục đăng ký đó cùng với các RFC được trích dẫn phổ biến nhất.