|
400
|
Bad Request
RFC 9110
|
Server không thể xử lý request vì cú pháp, tham số, header hoặc body không hợp lệ. |
Phổ biến với JSON không hợp lệ, thiếu giá trị bắt buộc, URL sai định dạng hoặc header bất thường. |
Kiểm tra định dạng request body, Content-Type, query parameter và log validation của server.
Liên quan: 422
|
|
401
|
Unauthorized
RFC 9110
|
Cần xác thực hoặc thông tin xác thực được cung cấp không hợp lệ. |
Dùng khi thiếu token đăng nhập, API key hết hạn hoặc header Authorization không đúng. |
Kiểm tra header WWW-Authenticate, thời hạn token, scheme xác thực và cookie có được gửi hay không.
Liên quan: 403, 407
|
|
402
|
Payment Required
RFC 9110
|
Được reserved cho tình huống cần thanh toán, nhưng ý nghĩa chuẩn chưa được thiết lập rộng rãi. |
Một số API và dịch vụ thanh toán dùng không chính thức cho vấn đề thanh toán, credit hoặc subscription. |
Kiểm tra tài liệu API riêng của dịch vụ để biết ý nghĩa thật sự của 402 và cách khôi phục.
Liên quan: 403, 429
|
|
403
|
Forbidden
RFC 9110
|
Server hiểu request nhưng từ chối cho phép truy cập. |
Phổ biến khi thiếu quyền, bị chặn IP, chính sách quản trị hoặc truy cập tài nguyên riêng tư. |
Kiểm tra riêng chính sách phân quyền, ACL, rule WAF, quyền file và rule routing, tách biệt với xác thực.
Liên quan: 401, 404, 451
|
|
404
|
Not Found
RFC 9110
|
Không tìm thấy tài nguyên được yêu cầu, hoặc server không tiết lộ liệu tài nguyên đó có tồn tại hay không. |
Thường gặp nhất với URL gõ sai, trang đã xóa, route không đúng hoặc tài nguyên được cố ý ẩn. |
Kiểm tra internal link, sitemap, redirect, bảng routing và URL thay thế cho nội dung đã xóa.
Liên quan: 410, 403, 451
|
|
405
|
Method Not Allowed
RFC 9110
|
Tài nguyên tồn tại, nhưng HTTP method được yêu cầu không được phép. |
Xảy ra khi gửi POST tới URL chỉ cho GET hoặc route API được cấu hình cho các method khác. |
Kiểm tra header Allow, định nghĩa method trong router và chính sách giới hạn method của proxy.
Liên quan: 404, 501
|
|
406
|
Not Acceptable
RFC 9110
|
Server không thể cung cấp representation khớp với các header Accept của client. |
Có thể xảy ra khi client chỉ yêu cầu media type, ngôn ngữ hoặc encoding không được hỗ trợ. |
Kiểm tra các header Accept, Accept-Language, Accept-Encoding và cấu hình content negotiation của server.
Liên quan: 415
|
|
407
|
Proxy Authentication Required
RFC 9110
|
Cần xác thực trước khi client có thể dùng proxy. |
Thường gặp trong mạng doanh nghiệp, proxy bảo mật và môi trường xác thực gateway. |
Kiểm tra header Proxy-Authenticate, Proxy-Authorization và cấu hình proxy mạng.
Liên quan: 401, 305
|
|
408
|
Request Timeout
RFC 9110
|
Server không nhận được request đầy đủ từ client trong khoảng thời gian sẵn sàng chờ. |
Có thể xảy ra với mạng chậm, upload lớn, timeout keep-alive hoặc timeout load balancer. |
Kiểm tra hành vi retry của client, kích thước upload, cài đặt keep-alive và giá trị timeout của proxy.
Liên quan: 504
|
|
409
|
Conflict
RFC 9110
|
Request xung đột với trạng thái hiện tại của tài nguyên. |
Thường dùng cho tạo trùng, xung đột phiên bản, chỉnh sửa đồng thời hoặc chuyển trạng thái không hợp lệ. |
Kiểm tra phiên bản tài nguyên, ETag, khóa trùng và rule chuyển trạng thái nghiệp vụ.
Liên quan: 412, 422
|
|
410
|
Gone
RFC 9110
|
Tài nguyên từng tồn tại nhưng đã bị xóa vĩnh viễn. |
Cụ thể hơn 404 khi bạn muốn báo rõ cho công cụ tìm kiếm và client rằng một trang đã bị xóa. |
Dùng 301 nếu có URL thay thế; dùng 410 cùng dọn sitemap khi việc xóa vĩnh viễn là đúng.
Liên quan: 404, 301
|
|
411
|
Length Required
RFC 9110
|
Server từ chối request vì không có Content-Length. |
Có thể xảy ra khi server hoặc gateway cần biết trước độ dài request body. |
Kiểm tra Content-Length, Transfer-Encoding và hành vi streaming của thư viện client.
Liên quan: 413
|
|
412
|
Precondition Failed
RFC 9110
|
Một điều kiện tiên quyết trong request có điều kiện, chẳng hạn If-Match, đã thất bại. |
Dùng để ngăn chỉnh sửa đồng thời, revalidate cache và cập nhật dựa trên ETag. |
So sánh If-Match, If-None-Match và If-Unmodified-Since với phiên bản tài nguyên hiện tại.
Liên quan: 304, 409, 428
|
|
413
|
Content Too Large
RFC 9110
|
Request body lớn hơn mức server sẵn sàng chấp nhận. |
Phổ biến với giới hạn upload file, giới hạn kích thước body JSON và giới hạn body của proxy. |
Kiểm tra giới hạn upload trên server, proxy, CDN và ứng dụng.
Liên quan: 411, 431
|
|
414
|
URI Too Long
RFC 9110
|
URI của request dài hơn mức server có thể xử lý. |
Có thể xảy ra với query string quá dài, vòng lặp redirect lỗi hoặc đưa quá nhiều dữ liệu vào URL GET. |
Chuyển dữ liệu dài vào body POST và kiểm tra giới hạn độ dài URI ở proxy và server.
Liên quan: 400, 431
|
|
415
|
Unsupported Media Type
RFC 9110
|
Server không hỗ trợ media type của request body. |
Xảy ra khi JSON API nhận Content-Type sai hoặc file format không được hỗ trợ được upload. |
Kiểm tra Content-Type, phần mở rộng file, cài đặt multipart và parser server đã được đăng ký hay chưa.
Liên quan: 406, 422
|
|
416
|
Range Not Satisfiable
RFC 9110
|
Range được yêu cầu không thể phục vụ vì không phù hợp với kích thước tài nguyên. |
Xảy ra trong download có thể tiếp tục hoặc streaming khi range được yêu cầu nằm ngoài kích thước file. |
Kiểm tra header Range, Content-Range, kích thước file và metadata cache đã cũ.
Liên quan: 206
|
|
417
|
Expectation Failed
RFC 9110
|
Server không thể đáp ứng kỳ vọng được nêu trong header Expect. |
Có thể xảy ra khi server hoặc proxy không hỗ trợ các kỳ vọng như Expect: 100-continue. |
Gỡ header Expect hoặc xác nhận server hỗ trợ xử lý 100 Continue.
Liên quan: 100
|
|
418
|
I'm a teapot
RFC 2324 / RFC 9110
|
Mã bắt nguồn từ RFC Cá tháng Tư, chủ yếu mang ý nghĩa lịch sử và văn hóa hơn là xử lý lỗi thực tế. |
Một số dịch vụ dùng cho phản hồi vui, test hoặc văn hóa developer, nhưng không nên dùng cho thiết kế API thông thường. |
Với API production, hãy dùng mã trạng thái 4xx hoặc 5xx rõ nghĩa và được định nghĩa tốt.
Liên quan: 400
|
|
421
|
Misdirected Request
RFC 9110
|
Request được gửi tới server không thể tạo phản hồi cho request đó. |
Có thể xảy ra khi tái sử dụng kết nối HTTP/2, TLS/SNI, CDN hoặc routing reverse proxy bị cấu hình sai. |
Kiểm tra Host, SNI, chứng chỉ, HTTP/2 connection coalescing và routing origin của CDN.
Liên quan: 400, 502
|
|
422
|
Unprocessable Content
RFC 9110
|
Cú pháp request hợp lệ, nhưng nội dung không thể xử lý về mặt ngữ nghĩa. |
Phổ biến với lỗi validation API, vi phạm rule nghiệp vụ và giá trị field không hợp lệ. |
Trong rule API của bạn, hãy quyết định 400 là lỗi định dạng còn 422 là lỗi ngữ nghĩa hoặc validation.
Liên quan: 400, 409, 415
|
|
423
|
Locked
RFC 4918
|
Tài nguyên đích đang bị khóa nên request không thể được xử lý. |
Dùng cho khóa chỉnh sửa file, tài liệu cộng tác và khóa tài nguyên WebDAV. |
Kiểm tra chủ sở hữu khóa, thời hạn khóa, API mở khóa và chính sách xử lý xung đột.
Liên quan: 409, 424
|
|
424
|
Failed Dependency
RFC 4918
|
Request hiện tại không thể thực hiện vì một thao tác phụ thuộc trước đó đã thất bại. |
Dùng khi nhiều thao tác phụ thuộc lẫn nhau và thất bại của thao tác trước làm thao tác sau thất bại. |
Làm rõ thao tác trước đã thất bại và quan hệ phụ thuộc trong response body.
Liên quan: 207, 423
|
|
425
|
Too Early
RFC 8470
|
Server từ chối xử lý request có thể còn quá sớm và có rủi ro khi replay. |
Có thể dùng với TLS 1.3 0-RTT early data khi tồn tại rủi ro replay attack. |
Đảm bảo request không idempotent không được gửi với 0-RTT và xác minh cài đặt client/server.
Liên quan: 429, 503
|
|
426
|
Upgrade Required
RFC 9110
|
Server yêu cầu client nâng cấp giao thức trước khi xử lý request. |
Dùng khi cần một nâng cấp cụ thể như phiên bản HTTP, TLS hoặc WebSocket. |
Kiểm tra header Upgrade, các giao thức được hỗ trợ và việc proxy có chuyển tiếp request nâng cấp hay không.
Liên quan: 101
|
|
428
|
Precondition Required
RFC 6585
|
Server yêu cầu header request có điều kiện. |
Dùng để ngăn mất cập nhật do chỉnh sửa đồng thời bằng cách yêu cầu điều kiện như If-Match. |
Cung cấp tài liệu API và thông báo lỗi yêu cầu client đọc ETag rồi cập nhật với If-Match.
Liên quan: 412, 409
|
|
429
|
Too Many Requests
RFC 6585
|
Client đã gửi quá nhiều request trong một khoảng thời gian nhất định. |
Phổ biến với giới hạn rate API, giới hạn thử đăng nhập, chặn bot và hành vi refresh quá mức. |
Kiểm tra Retry-After, header rate limit, giới hạn theo user hoặc token và chiến lược backoff.
Liên quan: 403, 503
|
|
431
|
Request Header Fields Too Large
RFC 6585
|
Toàn bộ request header hoặc một trường header cụ thể quá lớn. |
Có thể xảy ra khi cookie quá lớn hoặc token xác thực, tracking header, header do proxy thêm bị tích tụ. |
Giảm kích thước Cookie, kích thước header Authorization và các header do chuỗi proxy thêm vào.
Liên quan: 400, 413, 414
|
|
451
|
Unavailable For Legal Reasons
RFC 7725
|
Tài nguyên không thể được cung cấp vì lý do pháp lý. |
Dùng khi quyền truy cập nội dung bị hạn chế bởi lệnh tòa, yêu cầu chính phủ, thông báo bản quyền hoặc quy định địa phương. |
Xác nhận mã này được dùng để minh bạch hóa yêu cầu pháp lý, khác với 403 hoặc 404 chung chung.
Liên quan: 403, 404, 410
|