Lỗi HTTP 415 nguyên nhân do đâu? Kiểm tra và sửa lỗi Unsupported Media Type

Một request có thể đúng URL, đúng phương thức nhưng vẫn bị server từ chối chỉ vì định dạng dữ liệu không phù hợp. Mã trạng thái 415 thường xuất hiện trong quá trình gọi API, gửi JSON, form data hoặc upload file khi Content-Type và payload không đáp ứng yêu cầu của hệ thống. Cùng Viettel IDC tìm hiểu nguyên nhân và cách khắc phục lỗi 415 Unsupported Media Type hiệu quả.

Lỗi HTTP 415 là gì?

Lỗi HTTP 415 Unsupported Media Type là mã trạng thái cho biết máy chủ từ chối xử lý yêu cầu vì định dạng tải trọng (payload) hoặc kiểu dữ liệu được gửi lên không được máy chủ hỗ trợ. 

Ví dụ, API chỉ chấp nhận dữ liệu JSON với Content-Type: application/json, nhưng client lại gửi application/xml hoặc multipart/form-data. Khi đó, server có thể trả về lỗi 415 Unsupported Media Type dù URL, phương thức request và quyền truy cập đều đúng. Trong nhiều trường hợp, request vẫn đúng URL và đúng phương thức POST, PUT hoặc PATCH, nhưng server vẫn trả về lỗi 415 vì kiểu dữ liệu gửi lên không phù hợp với yêu cầu xử lý.

Nguyên nhân gây ra lỗi HTTP 415

Lỗi HTTP 415 xuất hiện khi định dạng dữ liệu trong request không phù hợp với kiểu nội dung mà server cho phép xử lý. Nguyên nhân thường nằm ở header, payload hoặc cách API được cấu hình.

Khai báo sai Content-Type

Đây là nguyên nhân phổ biến nhất của 415 Unsupported Media Type. Header Content-Type cho server biết request body đang chứa loại dữ liệu nào, chẳng hạn application/json, application/xml hoặc multipart/form-data. Nếu client gửi JSON nhưng lại khai báo Content-Type: text/plain, server có thể từ chối request và trả về lỗi 415.

Định dạng payload không khớp với Content-Type

Ngay cả khi Content-Type được khai báo đúng, lỗi vẫn có thể xảy ra nếu nội dung thực tế không đúng định dạng tương ứng. Ví dụ, request khai báo application/json nhưng body lại chứa dữ liệu không phải JSON hợp lệ. Trường hợp này thường gặp khi gọi API bằng POST, PUT hoặc PATCH, nhất là khi dữ liệu được tạo thủ công hoặc chuyển đổi qua nhiều lớp trung gian.

Server không hỗ trợ media type được gửi lên

Một API có thể chỉ cho phép một số định dạng nhất định. Nếu endpoint chỉ hỗ trợ application/json nhưng client gửi application/xml, server sẽ không có cơ chế xử lý dữ liệu đó và trả về lỗi 415 Unsupported Media Type. Vì vậy, cần đối chiếu media type trong request với tài liệu API thay vì chỉ kiểm tra cú pháp dữ liệu.

Request thiếu header Content-Type

Với các request có body, đặc biệt là request gửi dữ liệu đến API, việc thiếu Content-Type có thể khiến server không xác định được kiểu dữ liệu đang nhận. Tùy cấu hình, một số server vẫn tự nhận diện định dạng, nhưng nhiều API yêu cầu khai báo rõ Content-Type và sẽ trả về HTTP 415 nếu header này bị thiếu.

Sử dụng sai định dạng khi upload file

Lỗi 415 cũng có thể xuất hiện khi upload file nếu client gửi sai kiểu MIME hoặc dùng phương thức đóng gói dữ liệu không đúng yêu cầu. Chẳng hạn, endpoint yêu cầu multipart/form-data nhưng client lại gửi file dưới dạng application/octet-stream. Ngoài ra, server có thể giới hạn các MIME type được phép như image/jpeg, image/png hoặc application/pdf.

Content-Encoding không được server hỗ trợ

HTTP 415 không chỉ liên quan đến Content-Type. Server cũng có thể từ chối request nếu dữ liệu được mã hóa hoặc nén bằng một Content-Encoding mà hệ thống không hỗ trợ.

Ví dụ, client gửi request được nén bằng một cơ chế mà server không thể giải mã. Khi đó, request body có thể đúng định dạng nhưng vẫn không được xử lý.

Cấu hình API hoặc framework giới hạn kiểu dữ liệu

Một số framework và API gateway được cấu hình chỉ nhận một nhóm media type cụ thể. Nếu endpoint chưa bật parser tương ứng cho JSON, XML, form data hoặc multipart, request có thể bị chặn ngay từ lớp xử lý đầu vào.

Cách kiểm tra nguyên nhân lỗi 415 Unsupported Media Type

Để xác định chính xác nguyên nhân lỗi 415 Unsupported Media Type, cần kiểm tra cả định dạng dữ liệu gửi lên và cách server tiếp nhận request. Trong đó, Content-Type, request body và media type mà API hỗ trợ là những yếu tố cần ưu tiên đối chiếu trước.

Cách khắc phục lỗi HTTP 415

Để khắc phục lỗi HTTP 415, cần đảm bảo định dạng dữ liệu client gửi lên phù hợp với yêu cầu của server hoặc API. Nên ưu tiên kiểm tra Content-Type, request body và media type được hỗ trợ trước khi thay đổi cấu hình phía backend.

Thiết lập đúng Content-Type

Kiểm tra và khai báo Content-Type đúng với dữ liệu thực tế trong request, chẳng hạn application/json khi gửi JSON hoặc multipart/form-data khi upload file. Nếu header bị thư viện hoặc framework tự động ghi đè, hãy kiểm tra lại request thực tế bằng DevTools, Postman hoặc log ứng dụng.

Đảm bảo request body đúng định dạng

Content-Type đúng nhưng body sai cấu trúc vẫn có thể khiến server từ chối request. Với JSON, cần kiểm tra cú pháp, kiểu dữ liệu và cấu trúc key-value; với XML hoặc form data cũng phải tuân thủ định dạng mà endpoint yêu cầu. Khi sửa lỗi HTTP 415 khi gọi API, nên đối chiếu payload với mẫu request trong tài liệu API.

Gửi đúng media type mà API hỗ trợ

Không phải endpoint nào cũng nhận mọi loại dữ liệu. Nếu API chỉ hỗ trợ application/json nhưng client lại gửi XML, plain text hoặc form data, server có thể trả về 415 Unsupported Media Type. Vì vậy, cần kiểm tra tài liệu API hoặc cấu hình endpoint để xác định chính xác media type được chấp nhận.

Kiểm tra cấu hình khi upload file

Nếu lỗi xuất hiện khi tải file lên, hãy kiểm tra multipart/form-data, MIME type và định dạng file mà server cho phép. Không nên tự thiết lập boundary nếu thư viện HTTP đã tự tạo, đồng thời cần xác nhận endpoint có hỗ trợ loại file đang gửi hay không.

Kiểm tra Content-Encoding

Nếu request được nén bằng gzip, br hoặc phương thức khác, hãy xác nhận server có hỗ trợ Content-Encoding tương ứng. Có thể thử gửi request không nén để kiểm tra lỗi có liên quan đến bước giải mã dữ liệu hay không.

Điều chỉnh cấu hình server hoặc framework

Nếu request đã đúng nhưng lỗi HTTP 415 vẫn xuất hiện, nguyên nhân có thể nằm ở backend, API gateway hoặc framework chưa hỗ trợ media type đang sử dụng. Quản trị viên cần kiểm tra parser, rule xử lý request và danh sách kiểu dữ liệu được phép để điều chỉnh phù hợp.

Phân biệt lỗi HTTP 415 với 400, 406 và 422

Các mã lỗi 400, 406, 415 và 422 đều thuộc nhóm HTTP 4xx nhưng phản ánh những vấn đề khác nhau trong quá trình client gửi request đến server. Điểm khác biệt chính nằm ở việc request sai ở cấu trúc, định dạng dữ liệu, nội dung hay định dạng phản hồi mà client yêu cầu.

Kết luận

Thông qua bài viết, bạn đã có thể hiểu rõ lỗi HTTP 415 là gì, nguyên nhân thường gặp, cách kiểm tra và hướng khắc phục phù hợp. Đây là những thông tin cần thiết để xử lý lỗi nhanh hơn khi làm việc với website hoặc API.