413 request entity too large: Nguyên nhân và cách khắc phục

Khi tích hợp Zalo API, xây dựng cổng upload hoặc gửi dữ liệu từ ứng dụng lên máy chủ, bạn có thể gặp thông báo 413 request entity too large. Lỗi thường xuất hiện sau khi người dùng tải ảnh, video, tài liệu hoặc gửi một request có phần body lớn hơn giới hạn máy chủ cho phép. Vì request có thể bị chặn trước khi tới controller, lập trình viên đôi khi kiểm tra mã nguồn nhưng không thấy log xử lý tương ứng.

Muốn khắc phục đúng, cần xác định giới hạn nằm ở lớp nào: client, CDN, load balancer, reverse proxy, Nginx, Apache, PHP, framework backend hay API đích. Chỉ tăng một tham số nhưng bỏ qua các lớp còn lại có thể khiến lỗi tiếp tục xuất hiện. Nội dung dưới đây giải thích bản chất HTTP 413, cách kiểm tra và cấu hình trên các môi trường phổ biến.

413 request entity too large là gì?

HTTP 413 là mã trạng thái cho biết máy chủ từ chối xử lý vì nội dung request vượt quá giới hạn được cấu hình. Thông báo có thể hiển thị dưới các tên như “413 Request Entity Too Large”, “413 Payload Too Large” hoặc “Content Too Large”. Ý nghĩa chung vẫn là dữ liệu gửi lên quá lớn.

Phần bị giới hạn thường nằm trong request body. Đó có thể là file upload qua multipart/form-data, JSON chứa chuỗi dài, ảnh mã hóa Base64, tệp media hoặc một lô bản ghi gửi cùng lúc. Với upload multipart, tổng dung lượng request còn bao gồm các trường form và phần dữ liệu phụ, nên có thể lớn hơn kích thước file hiển thị trên máy tính.

Điểm cần lưu ý là lỗi có thể phát sinh trước khi request tới route của ứng dụng. Ví dụ, Nginx đứng trước Node.js chỉ cho phép 10 MB trong khi Express cho phép 50 MB. Khi đó, tăng giới hạn trong Express không có tác dụng vì request đã bị Nginx từ chối.

Trong hệ thống tích hợp Zalo API, lỗi có thể xuất hiện khi người dùng tải file lên máy chủ của bạn, khi backend chuyển tiếp file sang dịch vụ khác hoặc khi payload gửi tới endpoint vượt quy định của nhà cung cấp. Vì vậy, phải phân biệt giới hạn thuộc hạ tầng của bạn hay thuộc API bên ngoài.

Nguyên nhân phổ biến gây lỗi HTTP 413

File upload vượt mức cho phép

Nguyên nhân thường gặp nhất là ảnh, video, tài liệu hoặc file nén lớn hơn cấu hình máy chủ. Giới hạn body được đặt để giảm nguy cơ cạn bộ nhớ, đầy ổ đĩa, thời gian xử lý kéo dài và tấn công từ chối dịch vụ.

Một file gần sát giới hạn vẫn có thể bị từ chối vì request multipart có thêm overhead. Nếu máy chủ cho phép 10 MB, không nên coi file 10 MB là chắc chắn hợp lệ. Nên chừa một khoảng an toàn hoặc cấu hình giới hạn lớn hơn dung lượng file tối đa dự kiến.

Giới hạn không đồng nhất giữa nhiều lớp

Hệ thống thực tế thường đi qua CDN, load balancer, reverse proxy, web server và ứng dụng. Mỗi lớp có thể đặt một mức riêng; giới hạn hiệu lực thường là giá trị nhỏ nhất trên toàn bộ đường đi.

Ví dụ, Nginx cho phép 25 MB nhưng PHP đặt post_max_size là 8 MB. Request lớn hơn 8 MB vẫn thất bại dù Nginx đã được nâng giới hạn. Tương tự, gateway hoặc ingress controller có thể chặn trước khi request tới container backend.

JSON, Base64 hoặc batch dữ liệu quá lớn

Ảnh mã hóa Base64 thường làm payload lớn hơn file nhị phân gốc, đồng thời tăng chi phí bộ nhớ khi encode, decode và parse JSON. Nếu nhiều ảnh được gộp trong một request, body có thể tăng rất nhanh.

Lỗi 413 cũng xuất hiện khi ứng dụng gửi hàng nghìn đối tượng JSON, lịch sử hội thoại hoặc dữ liệu đồng bộ trong một lần. Khi đó, giải pháp phù hợp thường là chia lô, giới hạn số bản ghi và chỉ gửi trường thực sự cần thiết.

Middleware hoặc framework đặt giới hạn riêng

Express, Laravel, Spring Boot, PHP-FPM, middleware upload và API gateway đều có thể giới hạn request body. Vì vậy, việc tăng cấu hình tại web server chưa chắc đã đủ. Cần kiểm tra toàn bộ chuỗi xử lý thay vì chỉ nhìn vào một file cấu hình.

Cách xác định lớp đang trả lỗi 413

Trước tiên, hãy xem response header và nội dung trang lỗi. Nếu trang phản hồi mang giao diện mặc định của Nginx hoặc Apache, lỗi có khả năng phát sinh tại web server. Nếu response là JSON có cấu trúc riêng, cần kiểm tra gateway hoặc ứng dụng tương ứng.

Tiếp theo, kiểm tra access log và error log. Nếu ứng dụng không ghi nhận request tại route dự kiến, khả năng cao request chưa đi tới backend. Với Nginx, log thường cho biết client gửi body quá lớn; với Apache, log có thể ghi request vượt giới hạn.

Có thể dùng curl để tái hiện lỗi với một file xác định:

curl -i -X POST https://api.example.com/upload -F “[email protected]”

Hãy thử nhiều kích thước như 1 MB, 5 MB, 10 MB và 20 MB. Mốc bắt đầu thất bại giúp suy đoán giới hạn đang áp dụng. Trong trình duyệt, tab Network cũng cho biết mã trạng thái, response body và kích thước request.

Sau đó, lập bảng giới hạn của từng lớp: CDN, load balancer, Nginx hoặc Apache, runtime, framework và API đích. Nếu dùng Docker hoặc Kubernetes, kiểm tra thêm ingress, annotation và file cấu hình được mount vào container. Mục tiêu là bảo đảm mọi lớp cần thiết đều hỗ trợ mức dung lượng mong muốn.

Không nên tăng giới hạn lên giá trị cực lớn chỉ để thử. Hãy xác định nhu cầu thực tế, đặt mức hợp lý và kết hợp kiểm tra loại file, thời gian upload, quyền truy cập cùng dung lượng lưu trữ.

Cách khắc phục lỗi 413 trên Nginx

Nginx sử dụng directive client_max_body_size để giới hạn request body. Directive có thể đặt trong khối http, server hoặc location, tùy phạm vi muốn áp dụng.

Ví dụ cho phép tối đa 25 MB trên virtual host:

server {
listen 443 ssl;
server_name api.example.com;

client_max_body_size 25M;

location / {
proxy_pass http://backend;
}
}

Nếu chỉ endpoint upload cần nhận file lớn, nên giới hạn trong location:

location /api/upload {
client_max_body_size 50M;
proxy_pass http://backend;
}

Sau khi sửa, kiểm tra cú pháp và reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Nếu dùng Docker, hãy chắc chắn file cấu hình đã được mount đúng và container đang đọc phiên bản mới. Với Kubernetes Nginx Ingress, giới hạn body thường được cấu hình bằng annotation của ingress controller. Sau khi cập nhật manifest, cần kiểm tra resource đã được áp dụng.

Một lỗi phổ biến là sửa nhầm virtual host. Máy chủ có thể chứa nhiều file trong sites-available, conf.d hoặc các file được include. Lệnh sau giúp xem cấu hình Nginx đã hợp nhất:

sudo nginx -T

Từ kết quả này, bạn có thể xác nhận client_max_body_size thực sự nằm trong domain và route cần xử lý.

Cách khắc phục trên Apache và ứng dụng backend

Apache có thể giới hạn body bằng directive LimitRequestBody, thường tính theo byte. Có thể đặt trong virtual host, directory hoặc .htaccess nếu máy chủ cho phép override.

Ví dụ cho phép khoảng 25 MB:

<Directory “/var/www/html”>
LimitRequestBody 26214400

Sau khi chỉnh cấu hình, kiểm tra và reload:

sudo apachectl configtest
sudo systemctl reload apache2

Trên một số hệ điều hành, tên dịch vụ là httpd. Nếu dùng hosting chia sẻ, bạn có thể cần cấu hình qua .htaccess, bảng quản trị hoặc liên hệ nhà cung cấp.

Với PHP, cần kiểm tra upload_max_filesize và post_max_size. Giá trị post_max_size nên lớn hơn kích thước file tối đa vì request còn chứa dữ liệu form:

upload_max_filesize = 20M
post_max_size = 25M
memory_limit = 256M

Sau khi sửa php.ini, hãy reload PHP-FPM hoặc web server. Ứng dụng vẫn có thể có quy tắc validation riêng, vì vậy cần kiểm tra Laravel, WordPress hoặc framework đang dùng.

Với Node.js và Express, giới hạn JSON có thể được đặt như sau:

app.use(express.json({ limit: “10mb” }));
app.use(express.urlencoded({ extended: true, limit: “10mb” }));

Nếu upload multipart, cần xem giới hạn của Multer, Busboy hoặc middleware tương ứng. Cấu hình backend không thay thế giới hạn của Nginx, Apache hoặc gateway phía trước.

Xử lý phía client khi tích hợp Zalo API

Phía client nên kiểm tra kích thước file trước khi gửi. Điều này giúp người dùng nhận thông báo rõ ràng thay vì chờ upload rồi mới gặp lỗi. Với JavaScript, có thể đọc thuộc tính size của file:

const maxSize = 10 * 1024 * 1024;

if (file.size > maxSize) {
throw new Error(“Tệp vượt quá dung lượng 10 MB”);
}

Kiểm tra client chỉ cải thiện trải nghiệm, không thay thế validation trên server. Backend vẫn phải kiểm tra kích thước, MIME type, phần mở rộng và nội dung thực tế của file.

Với ảnh hoặc video, hãy nén hợp lý trước khi upload. Không nên nhúng file lớn vào JSON nếu API hỗ trợ multipart hoặc URL media. Một quy trình tốt là upload file lên kho lưu trữ, nhận URL hoặc media ID, sau đó gửi payload metadata nhẹ tới API.

Với dữ liệu dạng danh sách, hãy chia thành các batch nhỏ. Thay vì gửi 20.000 bản ghi trong một request, có thể chia thành các lô 200 hoặc 500 bản ghi. Mỗi batch nên có mã định danh để theo dõi, retry riêng và tránh ghi trùng.

Khi gọi Zalo API hoặc dịch vụ bên thứ ba, phải tuân thủ giới hạn của endpoint. Nếu lỗi 413 đến từ máy chủ nhà cung cấp, tăng giới hạn trên Nginx của bạn không giải quyết được. Cần giảm payload, dùng phương thức upload được hỗ trợ hoặc chia nhỏ dữ liệu.

Không nên retry nguyên trạng liên tục sau HTTP 413. Cùng payload và cùng giới hạn sẽ tiếp tục thất bại. Client nên dừng retry, ghi log kích thước request, endpoint và mã tương quan, sau đó trả hướng xử lý cụ thể.

Checklist phòng tránh 413 request entity too large

Để hạn chế 413 request entity too large, hãy xác định kích thước request tối đa ngay từ giai đoạn thiết kế. Mức giới hạn cần phù hợp với loại dữ liệu, năng lực máy chủ và yêu cầu bảo mật, thay vì tăng tùy tiện khi có lỗi.

Trước khi triển khai, hãy đồng bộ giới hạn trên CDN, load balancer, reverse proxy, web server, runtime, framework và API đích. Viết test cho các mốc nhỏ hơn giới hạn, gần ngưỡng và vượt ngưỡng. Response khi bị từ chối nên có thông báo dễ hiểu để client biết cần giảm dung lượng.

Hệ thống nên ghi log request size, route, loại nội dung và mã theo dõi, nhưng tránh ghi toàn bộ dữ liệu nhạy cảm. Với file lớn, ưu tiên upload trực tiếp lên object storage bằng URL ký sẵn rồi chỉ gửi metadata về backend tại zalo.

Cuối cùng, hãy xem HTTP 413 là tín hiệu cần điều chỉnh cả cấu hình lẫn cách truyền dữ liệu. Khi xác định đúng lớp trả lỗi, đồng bộ giới hạn và xử lý payload hợp lý từ phía client, quá trình tích hợp Zalo API hoặc ứng dụng web sẽ ổn định, dễ giám sát và an toàn hơn.