Bạn gọi API và nhận về 403. Là lỗi gì? Sai token hay bị block hẳn? Còn 422 khác 400 ở chỗ nào? Và tại sao có khi redirect lại dùng 301, có khi lại 302? Nếu bạn đã từng phân vân với những câu hỏi đó — trang này là tài liệu tham khảo nhanh bạn cần bookmark lại ngay.
HTTP status code là gì?
HTTP Status Code là mã số 3 chữ số mà server trả về trong mỗi HTTP response để cho client biết kết quả của request. Mã này được chuẩn hoá bởi IETF (RFC 9110) và được dùng thống nhất trên toàn bộ internet — từ trình duyệt, API, CDN cho đến load balancer.
Cấu trúc của một HTTP response bao giờ cũng có status code ở dòng đầu tiên, ví dụ: HTTP/1.1 200 OK hay HTTP/2 404 Not Found. Client (trình duyệt, mobile app, script…) đọc mã này để quyết định xử lý response như thế nào tiếp theo.
Toàn bộ status code được chia thành 5 nhóm theo chữ số đầu tiên:
| Nhóm | Phạm vi | Ý nghĩa chung |
|---|---|---|
| 1xx | 100–199 | Informational — Request đang được xử lý, chờ thêm |
| 2xx | 200–299 | Success — Request thành công |
| 3xx | 300–399 | Redirection — Cần thêm hành động để hoàn tất |
| 4xx | 400–499 | Client Error — Lỗi từ phía client |
| 5xx | 500–599 | Server Error — Lỗi từ phía server |
Nhóm 2xx — thành công
Đây là những gì bạn muốn thấy — server đã nhận, hiểu và xử lý thành công request.
| Mã | Tên | Ý nghĩa & khi nào dùng |
|---|---|---|
| 200 | OK | Request thành công. Mã phổ biến nhất — dùng cho GET, PUT, PATCH trả về dữ liệu. |
| 201 | Created | Resource mới được tạo thành công. Dùng sau POST tạo mới dữ liệu — nên kèm header Location trỏ đến resource vừa tạo. |
| 202 | Accepted | Request được chấp nhận nhưng chưa xử lý xong (async). Dùng cho các tác vụ nền như gửi email, export file lớn. |
| 204 | No Content | Thành công nhưng không có body trả về. Dùng sau DELETE hoặc PUT/PATCH không cần trả dữ liệu. |
| 206 | Partial Content | Trả về một phần nội dung — dùng cho download từng chunk, video streaming với Range request. |
Nhóm 3xx — redirect
Server yêu cầu client truy cập đến URL khác. Chọn sai mã redirect ảnh hưởng đến SEO và caching.
| Mã | Tên | Ý nghĩa & khi nào dùng |
|---|---|---|
| 301 | Moved Permanently | URL cũ đã chuyển vĩnh viễn sang URL mới. Trình duyệt và Google sẽ cache và cập nhật index. Dùng khi migrate domain hoặc đổi cấu trúc URL. |
| 302 | Found (Moved Temporarily) | Chuyển tạm thời — client không nên cache. Dùng cho redirect sau khi login, A/B testing, maintenance. |
| 304 | Not Modified | Resource không thay đổi kể từ lần cache cuối. Client dùng bản cache đang có — tiết kiệm bandwidth. Cơ chế của ETag và Last-Modified. |
| 307 | Temporary Redirect | Giống 302 nhưng bắt buộc giữ nguyên HTTP method (POST redirect vẫn là POST). Dùng khi method quan trọng. |
| 308 | Permanent Redirect | Giống 301 nhưng giữ nguyên method. Dùng thay 301 khi cần đảm bảo POST không bị chuyển thành GET. |
Nhóm 4xx — lỗi từ phía client
Client gửi request sai — sai URL, sai dữ liệu, thiếu quyền, hoặc request không được phép.
| Mã | Tên | Ý nghĩa & khi nào dùng |
|---|---|---|
| 400 | Bad Request | Request sai cú pháp hoặc dữ liệu không hợp lệ — server không thể hiểu. Dùng khi thiếu field bắt buộc, sai kiểu dữ liệu ở mức parse. |
| 401 | Unauthorized | Chưa xác thực — cần đăng nhập hoặc cung cấp token hợp lệ. Tên gọi hơi misleading: thực ra là unauthenticated, không phải unauthorized. |
| 403 | Forbidden | Đã xác thực nhưng không có quyền truy cập resource này. Khác 401 ở chỗ: server biết bạn là ai, nhưng vẫn từ chối. |
| 404 | Not Found | Resource không tồn tại tại URL này. Mã nổi tiếng nhất internet. Cũng có thể dùng thay 403 khi muốn ẩn sự tồn tại của resource. |
| 405 | Method Not Allowed | HTTP method không được hỗ trợ — ví dụ gửi DELETE đến endpoint chỉ chấp nhận GET. Nên kèm header Allow liệt kê method hợp lệ. |
| 408 | Request Timeout | Client gửi request quá chậm, server hết kiên nhẫn ngắt kết nối. |
| 409 | Conflict | Request xung đột với trạng thái hiện tại của resource — ví dụ tạo user với email đã tồn tại, hoặc version conflict khi update đồng thời. |
| 410 | Gone | Resource đã tồn tại nhưng bị xóa vĩnh viễn — khác 404 ở chỗ khẳng định chắc chắn đã bị xóa, không phải chưa bao giờ tồn tại. |
| 422 | Unprocessable Entity | Request đúng cú pháp nhưng dữ liệu không hợp lệ về mặt logic — ví dụ email sai định dạng, số âm khi cần số dương. Phổ biến trong REST API validation. |
| 429 | Too Many Requests | Client gửi quá nhiều request trong thời gian ngắn — bị rate limiting. Nên kèm header Retry-After cho biết chờ bao lâu. |
Nhóm 5xx — lỗi từ phía server
Request hợp lệ nhưng server gặp sự cố khi xử lý — đây là lỗi cần developer fix phía backend.
| Mã | Tên | Ý nghĩa & khi nào dùng |
|---|---|---|
| 500 | Internal Server Error | Lỗi chung phía server — exception không được handle, bug trong code. Đây là mã bạn không bao giờ muốn thấy trên production. |
| 501 | Not Implemented | Server không hỗ trợ chức năng cần thiết để xử lý request — thường dùng cho tính năng chưa phát triển. |
| 502 | Bad Gateway | Server đóng vai proxy/gateway nhận response không hợp lệ từ upstream server. Thường gặp khi app server bị crash hoặc khởi động lại. |
| 503 | Service Unavailable | Server tạm thời không khả dụng — quá tải hoặc đang maintenance. Nên kèm header Retry-After. |
| 504 | Gateway Timeout | Proxy/gateway không nhận được response từ upstream trong thời gian cho phép. Khác 502: không phải response sai, mà là không có response. |
Phân biệt các cặp dễ nhầm
| Cặp dễ nhầm | Điểm khác biệt mấu chốt |
|---|---|
| 400 vs 422 | 400: request sai cú pháp, server không parse được. 422: parse được nhưng dữ liệu sai logic (validation error). |
| 401 vs 403 | 401: chưa đăng nhập (unauthenticated). 403: đã đăng nhập nhưng không có quyền (unauthorized). |
| 404 vs 410 | 404: không tìm thấy (có thể chưa tồn tại hoặc đã xóa). 410: chắc chắn đã tồn tại và đã bị xóa vĩnh viễn. |
| 301 vs 302 | 301: redirect vĩnh viễn — Google chuyển link juice, trình duyệt cache. 302: redirect tạm thời — không cache, Google giữ index trang gốc. |
| 502 vs 504 | 502: upstream trả response sai/lỗi. 504: upstream không trả response (timeout). |
Kết luận
Hiểu đúng HTTP status code không chỉ giúp bạn debug nhanh hơn mà còn giúp thiết kế API chuẩn hơn — trả đúng mã cho đúng tình huống là một phần của good API design. Bookmark trang này để tra cứu nhanh mỗi khi cần.
Khám phá thêm các tool hữu ích tại codetuthub.com/tools.
0 Bình luận