Bạn gọi một API và nhận về con số 502. Bạn kiểm tra code frontend thì thấy đúng, gửi lại request vẫn lỗi, và bắt đầu nghi ngờ mọi thứ. Thực ra con số đó đã nói khá rõ nơi xảy ra vấn đề, nếu bạn biết cách đọc nó.
Mã trạng thái HTTP là gì
Mỗi khi trình duyệt hoặc ứng dụng gửi request tới server, server luôn trả về một mã ba chữ số kèm theo phản hồi. Mã này cho biết kết quả của request: thành công, cần chuyển hướng, client gửi sai, hay server gặp lỗi. Mã trạng thái không thay thế nội dung phản hồi, nhưng nó là dòng đầu tiên bạn nên nhìn khi có sự cố.
Các mã được chuẩn hóa trong RFC 9110, và mỗi mã có một ý nghĩa cố định. Điều đó giúp mọi công cụ, từ trình duyệt, proxy đến thư viện HTTP, hiểu cùng một cách.
Năm nhóm mã và ai chịu trách nhiệm
Chữ số đầu tiên cho biết nhóm mã:
| Nhóm | Ý nghĩa | Thường thuộc về |
|---|---|---|
| 1xx | Thông tin, request đang được xử lý | Không thường gặp khi lập trình |
| 2xx | Thành công | Không có lỗi |
| 3xx | Chuyển hướng | Cấu hình URL, cần kiểm tra thêm |
| 4xx | Lỗi phía client | Request gửi lên sai hoặc thiếu quyền |
| 5xx | Lỗi phía server | Server, gateway hoặc dịch vụ phía sau gặp vấn đề |
Quy tắc đơn giản nhất là: 4xx thường nghĩa là phía gọi cần sửa request, còn 5xx thường nghĩa là phía nhận cần kiểm tra hệ thống của mình.
Những mã gặp hằng ngày
Với 200 (OK), request thành công và phản hồi có nội dung. 201 (Created) cho biết tài nguyên mới đã được tạo, thường thấy khi gọi API thêm dữ liệu.
Với 301 và 302, trình duyệt được chuyển đến URL khác. 301 là chuyển hướng vĩnh viễn, 302 là tạm thời. Chuyển hướng sai là nguyên nhân phổ biến khi website đổi cấu trúc URL.
Với 400 (Bad Request), server không hiểu request, thường do JSON sai định dạng hoặc thiếu tham số. 401 (Unauthorized) nghĩa là chưa xác thực, tức chưa đăng nhập hoặc token hết hạn. 403 (Forbidden) nghĩa là đã xác thực nhưng không có quyền. Nhầm lẫn giữa 401 và 403 khá phổ biến và đáng để nhớ kỹ.
Với 404 (Not Found), tài nguyên không tồn tại tại địa chỉ đó. Với API, mã này thường nghĩa là không tìm thấy bản ghi, nhưng không phải lúc nào cũng vậy.
Với 500 (Internal Server Error), server gặp lỗi không xác định, thường là exception chưa được xử lý. Với 502 (Bad Gateway), một gateway hoặc proxy nhận phản hồi không hợp lệ từ server phía sau. Với 503 (Service Unavailable), server tạm thời không xử lý được request, thường do quá tải hoặc đang bảo trì. Với 504 (Gateway Timeout), gateway chờ server phía sau quá lâu mà không có phản hồi.
Cách khoanh vùng lỗi bằng mã trạng thái
Khi gặp lỗi, hãy bắt đầu từ mã. Nếu là 4xx, kiểm tra request: URL, method, header, body, và token. Nếu là 5xx, kiểm tra xem server, gateway hay dịch vụ phía sau đang lỗi, bằng cách xem log và trạng thái của từng thành phần. Với 502, 503, 504, đường đi của request thường dài hơn bạn nghĩ, nên cần xem từng chặng.
Một lưu ý quan trọng: không phải API nào cũng trả đúng mã. Có trường hợp lỗi nghiệp vụ vẫn trả 200 kèm trường error trong body. Vì vậy, mã trạng thái là điểm bắt đầu, không phải kết luận cuối cùng. Luôn đối chiếu với nội dung phản hồi và log.
Đọc mã trạng thái không cần nhớ hết hàng trăm mã. Nhớ nhóm, nhớ vài mã hay gặp, và biết hỏi “lỗi thuộc phía nào” trước, bạn đã rút ngắn được nhiều thời gian tìm lỗi.