API Error Handling là gì?
API Error Handling (xử lý lỗi API) là quá trình phát hiện, quản lý và phản hồi các lỗi xảy ra trong quá trình API tiếp nhận request hoặc xử lý yêu cầu. Mục tiêu là giúp API phản hồi một cách nhất quán, cung cấp thông tin lỗi phù hợp và duy trì hoạt động đáng tin cậy, dễ dự đoán.
Vai trò của API Error Handling
- Giao tiếp rõ ràng: Giúp phía gọi API (client/frontend) hiểu được vì sao yêu cầu thất bại thông qua HTTP Status Code và thông tin lỗi phù hợp. Ví dụ: dữ liệu không hợp lệ, không đủ quyền truy cập hoặc xảy ra lỗi phía máy chủ.
- Định dạng nhất quán: Trả về cấu trúc lỗi theo quy ước thống nhất để ứng dụng dễ dàng phân tích, xử lý và hiển thị thông báo phù hợp cho người dùng hoặc lập trình viên.
- Bảo mật hệ thống: Hạn chế việc tiết lộ thông tin nhạy cảm của hệ thống, chẳng hạn như stack trace, thông tin kết nối database hoặc chi tiết triển khai nội bộ. Những thông tin cần thiết để điều tra lỗi nên được ghi log ở phía server thay vì đưa toàn bộ vào response gửi cho client.
Các loại lỗi API thường gặp
Khi làm việc với REST API, lỗi có thể xảy ra ở phía client hoặc phía server. HTTP Status Code giúp xác định khái quát kết quả của request và hỗ trợ client lựa chọn cách xử lý phù hợp.
Có thể chia các mã trạng thái lỗi HTTP thành hai nhóm chính:
- Lỗi phía client (4xx): Cho biết request có vấn đề hoặc không thể được chấp nhận trong tình huống hiện tại. Nguyên nhân có thể là dữ liệu không hợp lệ, thiếu thông tin xác thực, không đủ quyền truy cập hoặc yêu cầu tài nguyên không tồn tại.
- Lỗi phía server (5xx): Cho biết server gặp sự cố hoặc không thể hoàn thành một request. Nguyên nhân có thể là lỗi nội bộ, dịch vụ phụ thuộc không hoạt động, quá tải hoặc hết thời gian chờ.
Việc phân loại này mang tính khái quát. Để xác định nguyên nhân cụ thể, cần xem thêm response body, tài liệu API và log khi có quyền truy cập.
1. Các mã trạng thái phía client (4xx)
400 Bad Request — Yêu cầu không hợp lệ
Mã 400 Bad Request cho biết server không thể hoặc không chấp nhận xử lý request do có vấn đề với yêu cầu gửi đến.
Nguyên nhân thường gặp:
- JSON sai cú pháp.
- Thiếu tham số hoặc trường bắt buộc theo quy định của API.
- Giá trị đầu vào không đáp ứng các điều kiện mà API yêu cầu.
Cách xử lý: Kiểm tra request body, query parameters, headers và tài liệu API để xác định dữ liệu nào cần điều chỉnh.
Một mã trạng thái liên quan là 422 Unprocessable Content (trước đây thường được gọi là Unprocessable Entity). Mã này có thể được sử dụng khi server hiểu nội dung request nhưng không thể xử lý do dữ liệu không đáp ứng các quy tắc đã đặt ra. Việc lựa chọn giữa 400 và 422 phụ thuộc vào quy ước của API.
401 Unauthorized — Chưa xác thực
Mã 401 Unauthorized cho biết request thiếu thông tin xác thực hợp lệ hoặc thông tin xác thực không được chấp nhận.
Nguyên nhân thường gặp:
- Không gửi access token.
- Token không hợp lệ hoặc đã hết hạn.
- Gửi thông tin xác thực sai định dạng.
Cách xử lý: Kiểm tra header Authorization và cách API yêu cầu truyền thông tin xác thực. Với nhiều API sử dụng Bearer Token, header có dạng:
Authorization: Bearer <token>Nếu token hết hạn, client có thể cần làm mới token hoặc đăng nhập lại, tùy cơ chế xác thực của hệ thống.
403 Forbidden — Bị từ chối truy cập
Mã 403 Forbidden cho biết server từ chối thực hiện yêu cầu vì client không có quyền truy cập hoặc thực hiện thao tác đó.
Ví dụ, người dùng đã đăng nhập nhưng cố gắng truy cập chức năng chỉ dành cho quản trị viên.
Cách xử lý: Kiểm tra quyền của tài khoản, vai trò người dùng và các quyền truy cập mà API yêu cầu.
Điểm khác biệt cơ bản giữa 401 và 403 là: 401 liên quan đến xác thực danh tính, còn 403 liên quan đến quyền thực hiện thao tác. Trong một số trường hợp bảo mật, API có thể sử dụng cách phản hồi khác để tránh tiết lộ thông tin về tài nguyên được bảo vệ.
404 Not Found — Không tìm thấy tài nguyên
Mã 404 Not Found cho biết server không tìm thấy tài nguyên tương ứng với request.
Ví dụ, client gửi request:
GET /api/products/9999 HTTP/1.1Nếu sản phẩm có ID 9999 không tồn tại, API có thể trả về 404 Not Found.
Nguyên nhân thường gặp:
- Đường dẫn URL không chính xác.
- ID của tài nguyên không tồn tại hoặc tài nguyên đã bị xóa.
- Client gọi nhầm phiên bản hoặc môi trường API.
Cách xử lý: Kiểm tra URL, ID tài nguyên, phiên bản API và môi trường đang sử dụng. Lưu ý rằng một số API cũng trả về 404 khi không muốn tiết lộ sự tồn tại của tài nguyên được bảo vệ.
429 Too Many Requests — Quá nhiều yêu cầu
Mã 429 Too Many Requests cho biết client đã gửi nhiều request hơn giới hạn mà API cho phép trong một khoảng thời gian.
Ví dụ, một ứng dụng gửi hàng trăm request liên tiếp trong thời gian ngắn và vượt quá giới hạn của nhà cung cấp API.
Cách xử lý:
- Giảm tần suất gửi request.
- Tận dụng cache nếu phù hợp.
- Gửi request theo lô khi API hỗ trợ.
- Thực hiện thử lại sau một khoảng thời gian phù hợp.
Nếu response có header Retry-After, client nên tuân theo thời gian chờ được chỉ định. Khi cần tự động thử lại, có thể dùng cơ chế exponential backoff, tức tăng dần thời gian chờ giữa các lần thử.
2. Các mã trạng thái phía server (5xx)
500 Internal Server Error — Lỗi máy chủ nội bộ
Mã 500 Internal Server Error cho biết server gặp một tình huống không mong muốn và không thể hoàn thành request.
Nguyên nhân thường gặp:
- Ngoại lệ chưa được xử lý trong chương trình.
- Lỗi khi truy cập database.
- Lỗi trong quá trình xử lý dữ liệu.
- Sự cố nội bộ của ứng dụng.
Cách xử lý: Nếu bạn là người sử dụng API, hãy thử lại sau nếu lỗi có vẻ tạm thời và liên hệ nhà cung cấp khi cần. Nếu bạn phát triển API, hãy kiểm tra log và thông tin theo dõi request để tìm nguyên nhân. Không nên đưa stack trace hoặc chi tiết nội bộ nhạy cảm vào response gửi cho client.
501 Not Implemented — Chưa được hỗ trợ triển khai
Mã 501 Not Implemented cho biết server không hỗ trợ chức năng cần thiết để thực hiện request.
Ví dụ, client sử dụng một tính năng hoặc phương thức mà server chưa triển khai hỗ trợ.
Cách xử lý: Kiểm tra tài liệu API để xác định chức năng được hỗ trợ. Nếu chức năng cần thiết chưa được triển khai, nhà phát triển hoặc nhà cung cấp API cần bổ sung hỗ trợ.
Cần phân biệt 501 với 405 Method Not Allowed: mã 405 được sử dụng khi phương thức HTTP không được phép đối với tài nguyên cụ thể, trong khi 501 liên quan đến chức năng server chưa hỗ trợ.
502 Bad Gateway — Cổng không hợp lệ
Mã 502 Bad Gateway thường xuất hiện khi một server hoạt động như gateway hoặc proxy nhận được phản hồi không hợp lệ từ server phía sau.
Ví dụ, API gateway chuyển request đến một dịch vụ khác nhưng dịch vụ đó trả về phản hồi không hợp lệ.
Cách xử lý: Client có thể thử lại nếu lỗi mang tính tạm thời. Nếu lỗi tiếp diễn, cần kiểm tra trạng thái dịch vụ phía sau, kết nối mạng và log của gateway hoặc liên hệ nhà cung cấp API.
503 Service Unavailable — Dịch vụ không khả dụng
Mã 503 Service Unavailable cho biết server tạm thời không thể xử lý request, thường do quá tải hoặc bảo trì.
Cách xử lý: Chờ một khoảng thời gian trước khi thử lại. Nếu response có header Retry-After, hãy sử dụng thông tin đó để xác định thời điểm thử lại. Nếu lỗi kéo dài, cần kiểm tra tình trạng dịch vụ hoặc liên hệ nhà cung cấp API.
504 Gateway Timeout — Gateway hết thời gian chờ
Mã 504 Gateway Timeout xảy ra khi gateway hoặc proxy không nhận được phản hồi kịp thời từ server phía sau để hoàn thành request.
Nguyên nhân thường gặp:
- Dịch vụ phía sau xử lý request quá lâu.
- Truy vấn database mất nhiều thời gian.
- Kết nối mạng giữa các dịch vụ gặp vấn đề.
- Thời gian chờ của gateway không đủ cho tác vụ đang thực hiện.
Cách xử lý: Nếu bạn là người sử dụng API, hãy thử lại sau nếu phù hợp và tránh gửi lặp lại các thao tác có thể tạo dữ liệu trùng. Nếu bạn phát triển hệ thống, hãy kiểm tra thời gian xử lý, truy vấn database, kết nối giữa các dịch vụ và cấu hình timeout.
API Error Handling hoạt động như thế nào?
Bước 1: Client gửi request Gửi dữ liệu, thông tin xác thực và yêu cầu đến API. Bước 2: Server kiểm tra request Kiểm tra dữ liệu đầu vào, xác thực, phân quyền và các điều kiện cần thiết. Bước 3: Xử lý yêu cầu Nếu hợp lệ, server thực hiện nghiệp vụ. Nếu xảy ra lỗi, server xác định và xử lý lỗi phù hợp. Bước 4: Trả response Trả HTTP Status Code và response body để client biết kết quả và xử lý tiếp.
Ví dụ thực tế
Giả sử một ứng dụng bán hàng cung cấp API để tạo sản phẩm mới. Client gửi request đến endpoint POST /api/products với dữ liệu:
Request:
POST /api/products
Content-Type: application/json{
"name": "Wireless Mouse",
"price": -100
}Trong ví dụ này, giá sản phẩm là -100, không đáp ứng quy tắc nghiệp vụ vì giá phải lớn hơn 0. Server sẽ kiểm tra dữ liệu đầu vào, phát hiện giá trị không hợp lệ và từ chối yêu cầu tạo sản phẩm.
Error Response:
HTTP/1.1 400 Bad Request
Content-Type: application/json{
"error": "Validation failed",
"message": "Price must be greater than 0"
}Response cho biết request không được chấp nhận và cung cấp thông tin về nguyên nhân xảy ra lỗi. Client có thể dựa vào thông tin này để hiển thị thông báo phù hợp cho người dùng hoặc yêu cầu nhập lại dữ liệu.
Nếu dữ liệu hợp lệ, server sẽ tiếp tục xử lý và tạo sản phẩm, sau đó trả về 201 Created.
Qua ví dụ trên, có thể thấy API Error Handling không chỉ là việc trả về HTTP Status Code mà còn bao gồm quá trình phát hiện lỗi, phản hồi thông tin phù hợp và giúp client biết cách xử lý tiếp theo.
Các nguyên tắc xử lý lỗi API
Để API dễ sử dụng, bảo trì và gỡ lỗi, việc xử lý lỗi cần tuân theo một số nguyên tắc nhất định.
1. Sử dụng thông báo lỗi rõ ràng
Khi xảy ra lỗi, API nên trả về HTTP Status Code phù hợp cùng thông tin giúp xác định nguyên nhân. Response có thể chứa một mã lỗi để máy dễ nhận diện và một thông báo dễ hiểu đối với con người.
Ví dụ, thay vì chỉ trả về thông báo chung chung như "Something went wrong", API có thể cung cấp mã lỗi payment_method_declined để client biết giao dịch bị từ chối do phương thức thanh toán không được chấp nhận.
Thông tin lỗi cần đủ rõ ràng để client biết cách xử lý, nhưng không nên tiết lộ dữ liệu nhạy cảm hoặc chi tiết nội bộ của hệ thống.
2. Ghi nhận và theo dõi lỗi tập trung
Ngoài việc trả thông tin lỗi cho client, server cần ghi nhận các lỗi quan trọng thông qua hệ thống logging và monitoring.
Việc theo dõi lỗi giúp lập trình viên phát hiện những vấn đề như số lượng lỗi tăng đột biến, một dịch vụ thường xuyên gặp sự cố hoặc một endpoint có tỷ lệ thất bại cao. Từ đó, họ có thể phân tích nguyên nhân và xử lý trước khi ảnh hưởng đến nhiều người dùng.
Tuy nhiên, log cần được quản lý phù hợp để tránh lưu trữ mật khẩu, token hoặc các thông tin nhạy cảm không cần thiết.
3. Sử dụng HTTP Status Code theo tiêu chuẩn
API nên sử dụng các HTTP Status Code tiêu chuẩn để biểu thị kết quả xử lý request. Ví dụ, 400 Bad Request cho request không hợp lệ, 404 Not Found khi không tìm thấy tài nguyên và 500 Internal Server Error khi xảy ra lỗi nội bộ ngoài dự kiến.
Không nên tự tạo mã trạng thái HTTP nằm ngoài phạm vi tiêu chuẩn. Nếu cần mô tả chi tiết hơn về lỗi, API nên sử dụng response body để cung cấp mã lỗi và thông tin bổ sung.
Cách này giúp client, proxy và các framework có thể hiểu và xử lý response theo quy ước HTTP.
4. Tập trung xử lý lỗi phía server
Trong các ứng dụng Backend, việc xử lý lỗi tại một vị trí chung giúp duy trì cấu trúc response nhất quán và giảm mã xử lý trùng lặp giữa các endpoint.
Ví dụ, một cơ chế xử lý lỗi tập trung có thể tiếp nhận các exception chưa được xử lý, ghi log cần thiết và chuyển chúng thành HTTP Status Code cùng response body theo định dạng thống nhất.
Tuy nhiên, những lỗi dự kiến như dữ liệu không hợp lệ hoặc không đủ quyền truy cập vẫn cần được xử lý phù hợp với từng tình huống. Không phải mọi lỗi đều nên được xem là lỗi nội bộ 500 Internal Server Error.
5. Kiểm thử cả các trường hợp lỗi
Kiểm thử API không chỉ tập trung vào những request hợp lệ mà còn cần kiểm tra các tình huống có thể gây lỗi, chẳng hạn dữ liệu đầu vào không hợp lệ, thiếu thông tin xác thực, không tìm thấy tài nguyên hoặc dịch vụ phụ thuộc không phản hồi.
Mỗi trường hợp cần được kiểm tra để bảo đảm API trả về HTTP Status Code và response body phù hợp, đồng thời không làm lộ thông tin nội bộ.
Kiểm thử các đường dẫn lỗi giúp phát hiện sớm những vấn đề trong quá trình xử lý request và hạn chế các lỗi có thể phát sinh khi API được sử dụng trong thực tế.
Kết luận
API Error Handling là một phần quan trọng trong quá trình xây dựng và phát triển API. Việc xử lý lỗi đúng cách giúp client hiểu được kết quả của request, hỗ trợ lập trình viên xác định nguyên nhân sự cố và giúp hệ thống hoạt động đáng tin cậy hơn.
Để đạt được điều đó, API cần sử dụng HTTP Status Code phù hợp, cung cấp thông tin lỗi rõ ràng, ghi nhận lỗi để theo dõi và kiểm thử các trường hợp thất bại. Đồng thời, việc xử lý lỗi nhất quán cũng giúp ứng dụng Backend dễ bảo trì và mở rộng hơn.
Hiểu và áp dụng tốt các nguyên tắc xử lý lỗi là một bước quan trọng để xây dựng API không chỉ hoạt động đúng trong điều kiện bình thường mà còn có thể phản hồi phù hợp khi xảy ra sự cố.
Nguồn tham khảo
Bài viết khác
JSON & HTTP Status Codes
JSON là gì? JSON (JavaScript Object Notation) là một định dạng dữ liệu dạng văn bản, có cấu trúc đơn giản và dễ đọc, thường được sử dụng để trao đổi dữ liệu giữa các chương trình. JSON tổ chức dữ liệu thông qua các cặp key-value, đối tượng (object) và mảng (array). Mặc dù […]
Go Channels & Go Context
1. Go Channels & Go Context là gì? Trong Go, goroutine cho phép chương trình chạy nhiều công việc đồng thời. Tuy nhiên, khi có nhiều goroutine cùng hoạt động, chúng cần một cách để trao đổi kết quả, phối hợp thời điểm thực thi và dừng công việc khi không còn cần thiết. Đây […]
Goroutine & Concurrency
1. Concurrency là gì? Concurrency là khả năng tổ chức nhiều công việc để chúng có thể tiến triển xen kẽ hoặc đồng thời trong cùng một khoảng thời gian. Thay vì phải thực hiện tất cả công việc theo một trình tự duy nhất, chương trình có thể chuyển đổi giữa nhiều công việc […]
Go Fundamentals
1. Go là gì? Go (Golang) là ngôn ngữ lập trình go thường được sử dụng trong backend, REST API, hệ thống mạng, công cụ dòng lệnh, cloud infrastructure và các dịch vụ chạy đồng thời. Go là ngôn ngữ biên dịch và có hệ thống kiểu dữ liệu tĩnh (statically typed). Điều này có […]
Laravel Routing & Controllers
1. Laravel Routing & Controllers là gì? Khi xây dựng backend bằng Laravel, client gửi HTTP request đến server để thực hiện một thao tác như lấy danh sách user, xem chi tiết sản phẩm hoặc tạo đơn hàng. Laravel cần xác định request đó sẽ được xử lý ở đâu và logic xử lý […]
Series 2 — Frontend Fundamentals: Responsive Web Design – Bootstrap
Series 2 — Frontend Fundamentals HTML → Sematic HTML → Forms & Validation → CSS Flexbox & Grid → Responsive Web Design → Bootstrap Bài 6. Responsive Web Design – Giao diện đa thiết bị 1. Responsive Web Design là gì? Khi xây dựng một website, chúng ta không thể giả định rằng […]
Khoá học lập trình game con rắn cho trẻ em 
