Các Mã Trạng Thái HTTP: Hướng Dẫn Đầy Đủ Cho Developer

Khi bạn nhấn F5 để reload trang, một cuộc “đối thoại” vô hình đang diễn ra giữa trình duyệt và máy chủ. Cuộc đối thoại đó bắt đầu bằng yêu cầu (request) và kết thúc bằng mã trạng thái HTTP – ba chữ số nhỏ bé nhưng mang thông điệp lớn về kết quả của mọi tương tác web.

Như một developer, bạn không chỉ cần đọc hiểu các mã này, mà còn phải sử dụng đúng chúng. Một header 404 sai nơi có thể khiến Google nghĩ trang bạn đã mất, một 500 không được bắt sẽ làm hỏng trải nghiệm người dùng. Bài viết này là tổng hợp đầy đủ và thực tế nhất về HTTP status codes – từ nguyên lý đến ứng dụng.

Tại Sao Mã Trạng Thái HTTP Quan Trọng?

• SEO & Ranking: Googlebot đọc status code để hiểu trang của bạn có tồn tại hay không. 301 đúng cách giữ nguyên PageRank, 404 khiến URL bị loại khỏi index.
• UX & Accessibility: Người dùng blind với screen reader cần thông báo lỗi rõ ràng. 403 Forbidden khác với 404 Not Found – một là “bạn không được phép”, hai là “không tìm thấy”.
• API Design: RESTful API dựa trên status code để biểu thị kết quả. 201 Created thay vì trả về { success: true } – đó là convention, không phải choice.
• Monitoring & Alerting: Log aggregation (ELK, Datadog) dựa trên status code để đếm lỗi, trigger alert. Tăng đột biến 5xx = server down.

Phân Loại Chi Tiết Từng Nhóm

HTTP status code gồm 5 chữ số: chữ số đầu tiên xác định lớp (class), hai chữ số sau xác định loại cụ thể. Dưới đây là danh sách đầy đủ nhất bạn cần biết.

1xx – Thông Báo (Informational)

Nhóm này hiếm gặp trong ứng dụng web thông thường. Chúng là “tín hiệu tạm thời” – máy chủ đã nhận request và đang xử lý, chưa trả về kết quả cuối.

2xx – Thành Công (Success)

Nhóm mong muốn nhất. Request đã được xử lý thành công. Dưới đây là các mã bạn sẽ gặp hàng ngày.

Best practice: Luôn trả về 201 Created với header Location: /resource/{id} khi tạo mới resource. Tránh dùng 200 OK cho POST tạo mới.

3xx – Chuyển Hướng (Redirection)

Client cần thực hiện thêm hành động. Đây là nhóm quan trọng cho SEO và caching.

Cache nuance: Chỉ browser cache 301 và 302 theo mặc định. 307 và 308 không được cache trừ khi có header Cache-Control rõ ràng.

4xx – Lỗi Phía Client (Client Error)

Request có vấn đề – sai cú pháp, thiếu quyền, hoặc resource không tồn tại. Client cần sửa request hoặc xác thực lại.

Security tip: Đừng bao giờ trả về stack trace hay chi tiết database error trong 400 hoặc 404. Thông tin đó giúp attacker reconnaissance. Log error internal, trả về generic message cho client.

5xx – Lỗi Phía Server (Server Error)

Máy chủ gặp lỗi khi xử lý request. Đây là lỗi nghiêm trọng – client không thể sửa, phải chờ developer fix.

Production checklist:

• Đừng bao giờ expose stack trace ra client (debug mode off)
• Log đầy đủ context: request ID, user ID, payload
• Trả về Retry-After header với 503 nếu biết thời gian maintenance
• Đặt monitoring alert cho mọi 5xx > 1% traffic

Code Examples Thực Tế

Dưới đây là cách implement đúng status code trong các framework phổ biến.

Node.js / Express

// POST create user – return 201 with Location header
app.post('/api/users', async (req, res) => {
  try {
    const user = await User.create(req.body);
    res.status(201)
       .location(`/api/users/${user.id}`)
       .json(user);
  } catch (err) {
    if (err.code === '23505') { // PostgreSQL duplicate key
      return res.status(409).json({ error: 'Email already exists' });
    }
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Rate limiting middleware – return 429
app.use('/api/', rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  handler: (req, res) => {
    res.status(429).json({
      error: 'Too many requests',
      retryAfter: Math.ceil(req.windowMs / 1000)
    });
  }
}));

// Controller method
public function store(Request $request)
{
    $validated = $request->validate([
        'email' => 'required|email|unique:users',
        'name' => 'required|string|max:255',
    ]);

    $user = User::create($validated);

    return response()->json($user, 201)
        ->header('Location', route('users.show', $user));
}

// Custom exception handler – return 404 for ModelNotFoundException
public function render($request, Throwable $exception)
{
    if ($exception instanceof ModelNotFoundException) {
        return response()->json(['error' => 'Not found'], 404);
    }
    return parent::render($request, $exception);
}

from fastapi import FastAPI, HTTPException, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    try:
        db_item = await save_item(item)
        return JSONResponse(
            status_code=201,
            content=db_item.dict(),
            headers={"Location": f"/items/{db_item.id}"}
        )
    except DuplicateError:
        raise HTTPException(status_code=409, detail="Item already exists")

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    item = await get_item(item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

# Giữ nguyên status code, serve custom page
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;

location = /404.html {
    internal; # Chỉ phục vụ nội bộ, không truy cập trực tiếp
    add_header Cache-Control "no-cache, must-revalidate";
}

location = /50x.html {
    internal;
    add_header Cache-Control "no-cache, must-revalidate";
}