Bạn đang tích hợp với một API mới. Bạn cẩn thận tạo một yêu cầu JSON với tất cả dữ liệu chính xác, gửi đi, và thay vì phản hồi thành công như mong đợi, bạn nhận lại một lỗi khó chịu: 415 Unsupported Media Type. Bạn kiểm tra lại xác thực, URL điểm cuối, tải trọng dữ liệu của mình – mọi thứ dường như đều đúng. Vậy điều gì đã sai?
Vấn đề có lẽ không phải ở những gì bạn gửi, mà là ở cách bạn cho máy chủ biết bạn đang gửi gì. Mã trạng thái phổ biến nhưng thường gây nhầm lẫn này hoàn toàn liên quan đến sự cố giao tiếp trong định dạng dữ liệu.
Lỗi 415 là cách máy chủ nói, "Tôi hiểu bạn đang cố gửi dữ liệu cho tôi, nhưng tôi không hiểu ngôn ngữ này. Tôi đã mong đợi bạn gửi nó ở một định dạng khác mà tôi thực sự có thể xử lý."
Nếu bạn là nhà phát triển làm việc với API – dù là xây dựng hay sử dụng chúng – việc hiểu mã trạng thái 415 là rất quan trọng để tích hợp suôn sẻ và tránh các phiên gỡ lỗi gây khó chịu.
Trong hướng dẫn chi tiết này, chúng ta sẽ khám phá ý nghĩa của mã trạng thái 415 Unsupported Media Type, lý do nó xảy ra, các kịch bản điển hình và những cách thực tế để khắc phục hoặc tránh nó. Cho dù bạn là nhà phát triển đang xử lý các tích hợp API hay tò mò về cách thức hoạt động của giao tiếp web, bài viết này sẽ giúp bạn nắm vững các lỗi 415.
Được rồi, hãy cùng đi sâu vào và làm rõ mọi sự nhầm lẫn xung quanh HTTP 415 một lần và mãi mãi.
Vấn đề: Nói ngôn ngữ của máy chủ
Hãy tưởng tượng bạn đang gửi một lá thư cho người chỉ đọc tiếng Pháp. Bạn có thể viết một lá thư tiếng Anh hùng hồn, cấu trúc hoàn hảo nhất, nhưng nếu người nhận không hiểu tiếng Anh, thông điệp của bạn sẽ vô dụng. Lỗi 415 là phiên bản kỹ thuật số của kịch bản này.
Các máy chủ web thường được xây dựng để hiểu các định dạng dữ liệu cụ thể. Chúng cần biết "ngôn ngữ" mà dữ liệu đến được viết bằng gì để có thể phân tích cú pháp và xử lý đúng cách. Tiêu đề Content-Type là cách máy khách cho máy chủ biết định dạng của dữ liệu.
HTTP 415 Unsupported Media Type thực sự có nghĩa là gì?
Mã trạng thái 415 Unsupported Media Type cho biết rằng máy chủ hiểu yêu cầu, nhưng nó từ chối chấp nhận vì định dạng tải trọng (loại phương tiện) không được máy chủ hỗ trợ cho tài nguyên được yêu cầu.
Nói một cách đơn giản hơn, máy khách của bạn (như Postman, Apidog hoặc trình duyệt của bạn) đang gửi dữ liệu ở định dạng mà máy chủ không hiểu hoặc không được cấu hình để xử lý.
Về cơ bản, máy chủ đang nói: "Tôi đã nhận dữ liệu của bạn, nhưng tôi không thể xử lý nó vì nó ở định dạng mà tôi không hiểu hoặc không hỗ trợ cho điểm cuối cụ thể này."
Một phản hồi 415 điển hình trông như thế này:
HTTP/1.1 415 Unsupported Media TypeContent-Type: application/json
{
"error": "Unsupported Media Type",
"message": "The request payload format is not supported.",
"supported_types": ["application/json", "application/xml"]
}
Điều này cho bạn biết, “Này! Tôi đã nhận được yêu cầu của bạn, nhưng tôi không thể xử lý loại nội dung này.”
Điều này thường liên quan đến giá trị của tiêu đề Content-Type trong yêu cầu HTTP, chỉ định định dạng của dữ liệu đang được gửi (như JSON, XML hoặc dữ liệu biểu mẫu nhiều phần). Một số máy chủ có thể cung cấp thông tin hữu ích hơn về các định dạng mà chúng hỗ trợ, trong khi những máy chủ khác có thể trả về một thông báo lỗi chung chung hơn.
Đi sâu: Định nghĩa kỹ thuật (dành cho người tò mò)
Theo đặc tả HTTP/1.1 (RFC 7231), Phần 6.5.13 định nghĩa mã trạng thái 415 như sau:
“Mã trạng thái 415 (Unsupported Media Type) cho biết máy chủ gốc từ chối phục vụ yêu cầu vì tải trọng ở định dạng không được phương thức này hỗ trợ trên tài nguyên đích.”
Điểm mấu chốt ở đây:
- Vấn đề nằm ở loại phương tiện, chứ không phải bản thân dữ liệu.
- Máy chủ biết bạn đang cố gửi gì – chỉ là nó không thể xử lý được.
Trọng tâm vấn đề: Tiêu đề Content-Type
Tiêu đề Content-Type là thông tin quan trọng quyết định liệu bạn sẽ nhận được lỗi 415 hay phản hồi thành công. Tiêu đề này cho máy chủ biết loại dữ liệu bạn đang gửi trong phần thân yêu cầu.
Dưới đây là các loại nội dung phổ biến nhất mà bạn sẽ gặp:
Các giá trị Content-Type phổ biến:
Đối với API JSON:
application/json- Tiêu chuẩn cho hầu hết các API REST hiện đạiapplication/json; charset=utf-8- JSON với mã hóa ký tự rõ ràng
Đối với dữ liệu biểu mẫu:
application/x-www-form-urlencoded- Định dạng gửi biểu mẫu HTML truyền thốngmultipart/form-data- Được sử dụng để tải lên tệp và biểu mẫu có tệp
Đối với XML:
application/xml- Định dạng XML tiêu chuẩntext/xml- Định dạng XML thay thế
Đối với văn bản thuần túy:
text/plain- Nội dung văn bản đơn giảntext/html- Nội dung HTML
Lỗi 415 xảy ra như thế nào: Phân tích từng bước
Hãy cùng xem chính xác điều gì xảy ra khi lỗi 415 xuất hiện.
Bước 1: Máy khách gửi yêu cầu
Một ứng dụng khách gửi yêu cầu đến một điểm cuối API của máy chủ. Ví dụ, giả sử chúng ta đang cố gắng tạo một người dùng mới:
POST /api/users HTTP/1.1Host: api.example.comContent-Type: application/xmlContent-Length: 125
<user><name>John Doe</name><email>john@example.com</email></user>
Bước 2: Máy chủ kiểm tra Content-Type
Máy chủ nhận yêu cầu và kiểm tra tiêu đề Content-Type. Nó thấy application/xml và kiểm tra cấu hình của nó cho điểm cuối /api/users.
Bước 3: Máy chủ nhận ra vấn đề
Điểm cuối /api/users của máy chủ được cấu hình chỉ chấp nhận application/json. Nó không có trình phân tích cú pháp XML được thiết lập cho điểm cuối này và nó không biết cách xử lý dữ liệu đến.
Bước 4: Phản hồi 415
Thay vì cố gắng xử lý dữ liệu không đúng định dạng (có thể dẫn đến lỗi hoặc vấn đề bảo mật), máy chủ phản hồi bằng mã trạng thái 415 Unsupported Media Type.
Bước 5: Máy khách nhận lỗi
Ứng dụng khách nhận phản hồi 415 và cần xử lý nó một cách thích hợp – thường là bằng cách sửa tiêu đề Content-Type và gửi lại yêu cầu.
Các kịch bản phổ biến bạn có thể gặp lỗi 415
1. Tải lên tệp trong API
Nếu bạn cố gắng tải lên một hình ảnh bằng application/json thay vì multipart/form-data, máy chủ sẽ không hiểu nội dung tệp.
2. API tùy chỉnh với xác thực nghiêm ngặt
Các API có xác thực schema nghiêm ngặt sẽ từ chối bất kỳ yêu cầu nào không khớp với quy tắc của chúng.
3. Ứng dụng di động sử dụng SDK lỗi thời
Đôi khi các SDK cũ hơn gửi yêu cầu với các tiêu đề lỗi thời, mà các API hiện đại không còn hỗ trợ.
4. Yêu cầu Cross-Origin (Các vấn đề về CORS)
Một số cấu hình CORS có thể hạn chế các loại nội dung được chấp nhận, gián tiếp gây ra phản hồi 415.
Vai trò của tiêu đề Content-Type
Tiêu đề Content-Type trong các yêu cầu HTTP cho máy chủ biết loại dữ liệu mà máy khách đang gửi.
Ví dụ:
application/jsoncho các tải trọng JSON.text/xmlcho dữ liệu XML.multipart/form-datacho việc tải lên tệp.
Nếu tiêu đề này bị thiếu hoặc chứa thông tin mà máy chủ không thể xử lý, bạn có thể sẽ thấy phản hồi 415.
Các kịch bản thực tế gây ra lỗi 415
Kịch bản 1: Thiếu tiêu đề Content-Type
POST /api/users HTTP/1.1Host: api.example.com
{"name": "John Doe", "email": "john@example.com"}
Nhiều máy chủ sẽ từ chối điều này vì không có tiêu đề Content-Type cho chúng biết cách diễn giải dữ liệu.
Kịch bản 2: Content-Type sai cho dữ liệu
POST /api/users HTTP/1.1Host: api.example.comContent-Type: application/x-www-form-urlencoded
{"name": "John Doe", "email": "john@example.com"}
Tiêu đề nói rằng đó là dữ liệu biểu mẫu, nhưng phần thân là JSON. Sự không khớp này làm máy chủ bối rối.
Kịch bản 3: Máy chủ không hỗ trợ định dạng
POST /api/users HTTP/1.1Host: api.example.comContent-Type: application/xml
<user><name>John</name></user>
Máy chủ có thể chỉ hỗ trợ JSON cho điểm cuối này, mặc dù XML được định dạng đúng.
Kiểm tra xử lý Content-Type với Apidog
Hãy cùng nói về cách Apidog có thể giúp cuộc sống của bạn dễ dàng hơn khi xử lý các lỗi này. Kiểm tra các loại nội dung khác nhau và đảm bảo API của bạn xử lý chúng đúng cách là nơi Apidog tỏa sáng. Nó giúp kiểm tra các kịch bản này cực kỳ dễ dàng mà không cần viết mã phức tạp.
Với Apidog, bạn có thể:
- Dễ dàng đặt tiêu đề Content-Type: Sử dụng giao diện trực quan của Apidog để chọn từ các loại nội dung phổ biến hoặc chỉ định các loại tùy chỉnh.
- Kiểm tra nhiều định dạng: Nhanh chóng kiểm tra cùng một điểm cuối với các loại nội dung khác nhau (JSON, XML, dữ liệu biểu mẫu) để xem máy chủ của bạn phản hồi như thế nào.
- Xác thực phản hồi lỗi: Đảm bảo API của bạn trả về các phản hồi
415thích hợp với các thông báo lỗi hữu ích khi nhận các định dạng không được hỗ trợ. - Kiểm tra các trường hợp biên: Thử nghiệm với các loại nội dung không đúng định dạng, thiếu tiêu đề hoặc dữ liệu không khớp để đảm bảo API của bạn xử lý chúng một cách linh hoạt.
- Tự động hóa kiểm tra Content-Type: Tạo các bộ kiểm thử tự động xác minh API của bạn chấp nhận đúng các định dạng được hỗ trợ và từ chối đúng các định dạng không được hỗ trợ.
Ví dụ, khi bạn thiết lập một yêu cầu POST trong Apidog, nó sẽ tự động áp dụng Content-Type chính xác dựa trên loại phần thân yêu cầu của bạn (JSON, XML, form-data, v.v.).
Điều đó có nghĩa là ít bất ngờ hơn và không còn lỗi 415 làm hỏng các phiên kiểm thử của bạn. Việc kiểm thử chủ động này có thể tiết kiệm hàng giờ gỡ lỗi và đảm bảo API của bạn hoạt động theo dự đoán.
415 so với các lỗi 4xx khác: Biết sự khác biệt
Điều quan trọng là phải phân biệt 415 với các lỗi máy khách khác:
400 Bad Request: Yêu cầu bị sai định dạng hoặc có lỗi cú pháp, bất kể loại nội dung.415 Unsupported Media Type: Yêu cầu được định dạng đúng, nhưng ở định dạng mà máy chủ không hỗ trợ cho điểm cuối này.406 Not Acceptable: Ngược lại với415– máy khách không thể chấp nhận định dạng phản hồi mà máy chủ muốn gửi.
Các phương pháp hay nhất để xử lý lỗi 415
Đối với người dùng API (Nhà phát triển máy khách):
- Luôn đặt tiêu đề Content-Type chính xác khớp với định dạng phần thân yêu cầu của bạn.
- Kiểm tra tài liệu API để xem loại phương tiện nào được hỗ trợ cho mỗi điểm cuối.
- Xử lý lỗi 415 một cách linh hoạt trong mã của bạn – đừng cho rằng máy chủ sẽ chấp nhận bất kỳ định dạng nào bạn gửi.
- Cung cấp hành vi dự phòng nếu có thể, chẳng hạn như chuyển đổi dữ liệu của bạn sang định dạng được hỗ trợ.
Đối với nhà cung cấp API (Nhà phát triển máy chủ):
- Hãy rõ ràng về các loại phương tiện được hỗ trợ trong tài liệu API của bạn.
- Trả về các thông báo lỗi hữu ích cho biết các loại phương tiện mà bạn hỗ trợ.
- Cân nhắc hỗ trợ nhiều định dạng nếu điều đó hợp lý cho API của bạn (ví dụ: cả JSON và XML).
- Sử dụng mã trạng thái HTTP thích hợp – đừng sử dụng
400khi bạn muốn nói415.
Ví dụ về phản hồi 415 được thiết kế tốt:
HTTP/1.1 415 Unsupported Media TypeContent-Type: application/json
{
"error": "unsupported_media_type",
"message": "This endpoint only accepts application/json payloads.",
"supported_types": ["application/json"],
"documentation": "<https://api.example.com/docs/content-types>"
}
Các lỗi Content-Type phổ biến gây ra 415
Dưới đây là một số cạm bẫy mà các nhà phát triển thường mắc phải:
| Lỗi | Mô tả | Ví dụ |
|---|---|---|
| Sử dụng tên tiêu đề sai | Lỗi chính tả hoặc vấn đề về chữ hoa/thường | contenttype thay vì Content-Type |
| Gửi dữ liệu biểu mẫu thay vì JSON | Máy chủ chỉ mong đợi JSON | application/x-www-form-urlencoded |
| Quên charset | Thiếu thông tin mã hóa | application/json; charset=utf-8 |
| Gửi phần thân trống | Thiếu tải trọng bắt buộc | POST /api không có dữ liệu |
| Sử dụng loại tệp không được hỗ trợ | Định dạng tải lên sai | Tải lên .exe thay vì .png |
Những lỗi này có vẻ nhỏ nhưng có thể gây ra lỗi yêu cầu lớn.
Các cách khắc phục phổ biến cho lỗi 415
Nếu bạn gặp lỗi 415, đây là những giải pháp phổ biến nhất:
Thêm tiêu đề Content-Type bị thiếu:
POST /api/users HTTP/1.1Content-Type: application/json
Sửa tiêu đề Content-Type:
# Trước (sai):
Content-Type: text/plain
# Sau (đúng):
Content-Type: application/json
Chuyển đổi dữ liệu của bạn sang định dạng được hỗ trợ:
Nếu máy chủ chỉ chấp nhận JSON, hãy đảm bảo bạn đang gửi JSON đúng cách, không phải XML hay dữ liệu biểu mẫu.
Kiểm tra lỗi chính tả:
# Sai:
Content-Type: application/jason
# Đúng:
Content-Type: application/json
Các cân nhắc nâng cao
Thương lượng nội dung (Content Negotiation)
Một số API tinh vi hỗ trợ thương lượng nội dung, nơi máy khách có thể chỉ định các định dạng mà nó có thể chấp nhận bằng cách sử dụng tiêu đề Accept:
GET /api/users/123 HTTP/1.1Accept: application/json, application/xml;q=0.9
Điều này cho máy chủ biết "Tôi ưu tiên JSON, nhưng tôi có thể chấp nhận XML nếu cần."
Tham số Charset
Đối với các định dạng dựa trên văn bản, bạn có thể cần chỉ định mã hóa ký tự:
Content-Type: application/json; charset=utf-8
Kết luận: Tầm quan trọng của giao tiếp rõ ràng
Mã trạng thái HTTP 415 Unsupported Media Type làm nổi bật một khía cạnh cơ bản của giao tiếp web: cả hai bên cần đồng ý về "ngôn ngữ" mà họ đang sử dụng để trao đổi dữ liệu. Không đủ chỉ gửi đúng dữ liệu – bạn phải gửi nó ở đúng định dạng và thông báo rõ ràng đó là định dạng gì.
HTTP 415 Unsupported Media Type là một phần quan trọng để đảm bảo rằng các máy chủ chỉ xử lý các định dạng dữ liệu tương thích và được mong đợi. Xử lý đúng các tiêu đề Content-Type, tuân thủ các đặc tả API và kiểm tra bằng các công cụ như Apidog có thể giảm đáng kể các lỗi này.
Hiểu và xử lý đúng cách các lỗi 415 sẽ giúp bạn trở thành một người dùng API hiệu quả hơn và một nhà thiết kế API giỏi hơn. Bằng cách chú ý đến các loại nội dung và cung cấp giao tiếp rõ ràng giữa máy khách và máy chủ, bạn có thể tránh các lỗi khó chịu này và xây dựng các tích hợp mạnh mẽ hơn. Hãy nhớ rằng API phát triển nhờ giao tiếp rõ ràng giữa máy khách và máy chủ. Nếu chúng nói cùng một "ngôn ngữ" (trong trường hợp này là loại phương tiện), mọi thứ sẽ diễn ra suôn sẻ.
Vì vậy, lần tới khi bạn gặp lỗi 415, hãy nhớ rằng đó không phải là một lỗi máy chủ phức tạp – đó là một vấn đề giao tiếp đơn giản thường dễ khắc phục. Và khi bạn đang xây dựng hoặc kiểm thử API, việc sử dụng một công cụ như Apidog sẽ giúp bạn đảm bảo rằng các loại nội dung của bạn luôn chính xác, ngăn chặn những lỗi này trước khi chúng xảy ra.