HTTP 415错误修复指南：解决Unsupported Media Type问题-牛站云

HTTP 415通常表示服务器拒绝处理当前请求，因为请求携带的数据格式或媒体类型不符合接口要求。完整错误名称是 Unsupported Media Type，也就是“不支持的媒体类型”。

这个状态码经常出现在 REST API、前后端分离项目、文件上传接口以及微服务调用场景中。尤其是使用 POST、PUT、PATCH 请求提交 JSON 数据时，如果 Content-Type 设置错误，很容易直接得到 415 响应。

HTTP 415错误是什么意思

HTTP 415属于客户端请求错误，核心问题不是网络连接失败，而是服务器无法按照接口声明的方式处理请求内容。

例如，后端接口要求接收 JSON：

http
POST /api/user
Content-Type: application/json

{
    "name": "Tom",
    "age": 25
}

如果客户端却发送：

http
POST /api/user
Content-Type: text/plain

{"name":"Tom","age":25}

虽然请求正文看起来仍然是 JSON，但请求头声明的数据类型是 text/plain。服务器根据 Content-Type 判断请求格式后，可能无法找到对应的解析器，于是返回：

http
HTTP/1.1 415 Unsupported Media Type

因此，遇到415错误时，首先应该检查请求头中的媒体类型、请求正文格式以及服务端接口支持的类型是否一致。

HTTP 415与Content-Type的关系

排查415错误时，Content-Type 是最重要的检查项之一。

常见的请求媒体类型包括：

Content-Type	典型用途
`application/json`	JSON接口请求
`application/x-www-form-urlencoded`	表单键值对提交
`multipart/form-data`	文件上传、混合表单
`text/plain`	纯文本数据
`application/xml`	XML数据
`application/octet-stream`	二进制数据

例如后端定义接口接收JSON：

Java
@PostMapping("/users")
public User createUser(@RequestBody User user) {
    return user;
}

客户端就应该发送：

http
Content-Type: application/json

而不是：

http
Content-Type: text/plain

需要特别注意的是，请求正文是什么格式与Content-Type声明的是什么格式必须保持一致。

常见HTTP 415错误原因

1. Content-Type设置错误

这是最常见的原因。

例如使用JavaScript发送JSON：

JavaScript
fetch("/api/users", {
    method: "POST",
    body: JSON.stringify({
        name: "Tom",
        age: 25
    })
});

虽然通过 JSON.stringify() 将对象转换成了JSON字符串，但没有明确设置 Content-Type。

建议写成：

JavaScript
fetch("/api/users", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        name: "Tom",
        age: 25
    })
});

这里有两个动作缺一不可：

使用 JSON.stringify() 序列化JavaScript对象。
使用 Content-Type: application/json 告诉服务器数据类型。

2. 请求体格式与Content-Type不匹配

例如：

http
Content-Type: application/json

但实际发送的是：


name=Tom&age=25

这实际上更接近：

http
Content-Type: application/x-www-form-urlencoded

如果服务端严格检查请求媒体类型，就可能返回415。

正确的JSON请求应该类似：

JSON
{
    "name": "Tom",
    "age": 25
}

对应：

http
Content-Type: application/json

3. 文件上传错误设置Content-Type

文件上传是另一个容易产生415的场景。

例如前端使用 FormData：

JavaScript
const formData = new FormData();

formData.append("file", file);
formData.append("name", "test");

fetch("/api/upload", {
    method: "POST",
    body: formData
});

这种情况下通常不要手动设置：

JavaScript
headers: {
    "Content-Type": "multipart/form-data"
}

因为浏览器会自动生成类似：

http
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary...

其中 boundary 用于分隔不同表单字段。

如果手动覆盖Content-Type而没有正确提供boundary，服务器可能无法正确解析上传数据，从而产生415或其他请求解析错误。

4. 后端接口只支持特定媒体类型

有些API明确限制了请求格式。

例如Spring Boot接口：

Java
@PostMapping(
    value = "/users",
    consumes = MediaType.APPLICATION_JSON_VALUE
)
public User create(@RequestBody User user) {
    return user;
}

这里的 consumes 表示接口只接受：


application/json

如果客户端发送：

http
Content-Type: application/xml

服务器就可能返回415。

因此，不能只看客户端代码，还需要确认服务端接口的 consumes、请求模型以及消息转换器配置。

使用Postman排查415错误

Postman是排查HTTP 415非常方便的工具。

假设接口：


POST http://localhost:8080/api/users

需要提交JSON。

在Postman中选择：

Body → raw → JSON

然后输入：

JSON
{
    "name": "Tom",
    "age": 25
}

Postman通常会自动设置：

http
Content-Type: application/json

也可以打开Headers检查是否存在：

http
Content-Type: application/json

如果当前请求是：

http
Content-Type: text/plain

则应该调整为接口实际要求的类型。

Postman排查重点

建议依次检查：


请求方法
    ↓
请求URL
    ↓
Content-Type
    ↓
请求Body
    ↓
Accept
    ↓
服务端接口定义

其中不要把 Accept 和 Content-Type 混淆。

Content-Type 描述的是：

我发送给服务器的数据是什么类型。

Accept 描述的是：

我希望服务器返回什么类型的数据。

例如：

http
Content-Type: application/json
Accept: application/json

表示客户端发送JSON，同时希望服务器返回JSON。

Axios出现415错误怎么解决

Axios调用接口时，可以直接指定请求头：

JavaScript
import axios from "axios";

axios.post(
    "/api/users",
    {
        name: "Tom",
        age: 25
    },
    {
        headers: {
            "Content-Type": "application/json"
        }
    }
);

如果服务器要求JSON，这种写法通常比较直观。

如果提交的是表单：

JavaScript
const params = new URLSearchParams();

params.append("username", "Tom");
params.append("password", "123456");

axios.post("/login", params);

此时请求内容与JSON不同，应该按照接口实际要求使用对应的媒体类型。

不要为了“解决415”而无条件把所有请求都设置成：

http
Content-Type: application/json

接口需要什么格式，客户端就应该发送什么格式。

Java调用接口出现415

Java客户端调用HTTP API时，同样需要检查请求头。

例如使用Java 11 HttpClient：

Java
HttpClient client = HttpClient.newHttpClient();

String json = """
{
    "name": "Tom",
    "age": 25
}
""";

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("http://localhost:8080/api/users"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(json))
        .build();

HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.statusCode());
System.out.println(response.body());

如果接口要求JSON，这里最关键的是：

Java
.header("Content-Type", "application/json")

同时请求正文也必须是真正符合JSON语法的数据。

Spring Boot中的HTTP 415排查

Spring Boot项目中，415错误通常与 @RequestBody、consumes、消息转换器以及客户端请求头有关。

例如：

Java
@PostMapping("/user")
public String addUser(@RequestBody User user) {
    return "success";
}

客户端需要发送JSON：

http
Content-Type: application/json

请求正文：

JSON
{
    "name": "Tom",
    "age": 25
}

如果客户端发送：

http
Content-Type: application/x-www-form-urlencoded

Spring无法按照当前接口的请求体定义进行转换时，就可能返回415。

也可以明确指定：

Java
@PostMapping(
    value = "/user",
    consumes = MediaType.APPLICATION_JSON_VALUE
)
public String addUser(@RequestBody User user) {
    return "success";
}

这样接口的媒体类型要求更加清晰。

Spring Boot出现415时检查MessageConverter

Spring MVC依靠 HttpMessageConverter 将HTTP请求体转换成Java对象。

例如JSON请求通常需要对应的JSON消息转换能力。

如果项目依赖、转换器配置或者自定义配置存在问题，即使：

http
Content-Type: application/json

也可能无法正常处理请求。

因此，遇到Spring Boot 415时，不要只盯着前端代码，还应该查看服务端日志以及HTTP消息转换相关异常。

文件上传接口出现415

假设Spring Boot文件上传接口：

Java
@PostMapping(
    value = "/upload",
    consumes = MediaType.MULTIPART_FORM_DATA_VALUE
)
public String upload(@RequestParam("file") MultipartFile file) {
    return file.getOriginalFilename();
}

客户端应该使用 multipart/form-data。

JavaScript示例：

JavaScript
const formData = new FormData();
formData.append("file", file);

fetch("/upload", {
    method: "POST",
    body: formData
});

这里不需要手动设置：

JavaScript
Content-Type: multipart/form-data

让浏览器自动生成完整的 Content-Type 和 boundary 通常更加可靠。

curl测试HTTP 415

如果怀疑前端代码存在问题，可以使用curl直接测试接口。

发送JSON：

Bash
curl -X POST "http://localhost:8080/api/users" 
  -H "Content-Type: application/json" 
  -d '{"name":"Tom","age":25}'

如果接口正常返回，而前端仍然出现415，问题大概率存在于前端请求构造过程。

也可以故意发送错误类型进行对比：

Bash
curl -X POST "http://localhost:8080/api/users" 
  -H "Content-Type: text/plain" 
  -d '{"name":"Tom","age":25}'

如果第二个请求返回415，就可以进一步确认服务端对媒体类型进行了限制。

HTTP 415与400、406有什么区别

这几个状态码非常容易混淆。

400 Bad Request

表示请求本身存在问题，例如参数格式错误、JSON语法错误等。

例如：

JSON
{
    "name": "Tom",
    "age":
}

这是非法JSON，服务器可能返回400。

415 Unsupported Media Type

重点是：

服务器不支持客户端发送的数据媒体类型。

例如接口要求：

http
Content-Type: application/json

客户端却发送：

http
Content-Type: application/xml

可能返回415。

406 Not Acceptable

406更多与 Accept 请求头有关。

例如客户端发送：

http
Accept: application/xml

但服务器无法提供XML格式的响应，就可能返回406。

可以简单理解为：


400：请求内容有问题
415：发送的数据类型不符合要求
406：服务器无法提供客户端要求的响应类型

排查HTTP 415的高效方法

实际开发中，不建议一上来就修改大量代码。按照请求链路逐层定位通常更快。

第一步：确认接口要求

查看API文档或者后端代码，确认接口要求：


POST /api/user
Content-Type: application/json

还是：


POST /api/upload
Content-Type: multipart/form-data

或者：


Content-Type: application/x-www-form-urlencoded

第二步：查看浏览器Network

打开浏览器开发者工具：


F12
→ Network
→ 找到失败请求
→ Headers
→ Request Headers

重点查看：


Content-Type
Accept
Authorization

然后查看Request Payload，确认请求正文是否真的符合声明的格式。

第三步：对比正常请求

如果项目之前存在正常请求，可以直接比较两个请求：


URL
HTTP Method
Content-Type
Accept
Request Payload
Authorization

很多415问题通过这种方式几分钟就能定位。

第四步：脱离前端进行测试

使用curl或Postman重新请求接口。

如果Postman正常而浏览器失败，优先检查前端代码。

如果Postman同样返回415，则继续检查后端接口定义。

第五步：查看服务端日志

服务端日志通常比HTTP状态码本身提供更多信息。

例如Spring Boot日志可能明确提示无法找到对应的HTTP消息转换器，或者请求媒体类型不被当前接口支持。

根据异常信息继续检查依赖、接口注解和请求格式，比单纯修改请求头更加可靠。

不要用“关闭校验”解决415

有些情况下，开发者为了快速绕过415，会尝试让服务器接受任意Content-Type，例如：

*/*

或者修改服务端配置，使接口不再严格限制媒体类型。

这种方式并不适合作为常规解决方案。

HTTP接口的媒体类型约束本身就是为了让客户端和服务器明确约定数据格式。如果客户端发送JSON，却错误声明为文本，真正应该修复的是请求构造逻辑，而不是简单取消服务端检查。

尤其是在生产环境中，过度放宽媒体类型限制还可能导致数据解析行为不一致。

HTTP 415错误修复检查清单

遇到 415 Unsupported Media Type 时，可以按照下面的顺序检查：


□ 确认API实际支持的Content-Type
□ 检查客户端Content-Type是否正确
□ 检查请求Body是否与Content-Type匹配
□ JSON请求是否使用JSON.stringify()
□ 文件上传是否错误手动设置multipart/form-data
□ 检查Spring Boot的@RequestBody
□ 检查@PostMapping的consumes配置
□ 检查HTTP消息转换器
□ 使用Postman或curl复现
□ 查看服务端日志
□ 检查代理、网关是否修改请求头

如果经过以上检查仍然无法解决，还需要关注API网关、Nginx、反向代理以及自定义过滤器等中间层。有些系统会在请求到达真正的业务服务之前修改或限制 Content-Type。

HTTP 415的核心并不复杂：客户端声明的数据类型、实际发送的数据以及服务端允许接收的数据类型必须保持一致。只要围绕这三个环节逐层检查，绝大多数 Unsupported Media Type 问题都可以快速定位并修复。

HTTP 415错误修复指南：解决Unsupported Media Type问题

HTTP 415错误是什么意思

HTTP 415与Content-Type的关系

常见HTTP 415错误原因

1. Content-Type设置错误

2. 请求体格式与Content-Type不匹配

3. 文件上传错误设置Content-Type

4. 后端接口只支持特定媒体类型

使用Postman排查415错误

Postman排查重点

Axios出现415错误怎么解决

Java调用接口出现415

Spring Boot中的HTTP 415排查

Spring Boot出现415时检查MessageConverter

文件上传接口出现415

curl测试HTTP 415

HTTP 415与400、406有什么区别

400 Bad Request

415 Unsupported Media Type

406 Not Acceptable

排查HTTP 415的高效方法

第一步：确认接口要求

第二步：查看浏览器Network

第三步：对比正常请求

第四步：脱离前端进行测试

第五步：查看服务端日志

不要用“关闭校验”解决415

HTTP 415错误修复检查清单

推荐模板

推荐服务

HTTP 415错误修复指南：解决Unsupported Media Type问题

HTTP 415错误是什么意思

HTTP 415与Content-Type的关系

常见HTTP 415错误原因

1. Content-Type设置错误

2. 请求体格式与Content-Type不匹配

3. 文件上传错误设置Content-Type

4. 后端接口只支持特定媒体类型

使用Postman排查415错误

Postman排查重点

Axios出现415错误怎么解决

Java调用接口出现415

Spring Boot中的HTTP 415排查

Spring Boot出现415时检查MessageConverter

文件上传接口出现415

curl测试HTTP 415

HTTP 415与400、406有什么区别

400 Bad Request

415 Unsupported Media Type

406 Not Acceptable

排查HTTP 415的高效方法

第一步：确认接口要求

第二步：查看浏览器Network

第三步：对比正常请求

第四步：脱离前端进行测试

第五步：查看服务端日志

不要用“关闭校验”解决415

HTTP 415错误修复检查清单

相关文章

推荐阅读

推荐模板

推荐服务