在访问网站、调用 API 或进行自动化数据采集时，请求失败并不一定意味着网络连接出现问题。除了之前介绍的HTTP 503 错误，今天继续了解另一种常见状态码：HTTP 415 Unsupported Media Type（不支持的媒体类型）。
在 API 调试、网页表单提交或前后端数据交互时，如果请求格式或编码方式不符合服务端要求，就可能触发 415 错误。本文将介绍其常见原因及排查修复方法。
一、HTTP 415 是什么？
HTTP 415（Unsupported Media Type）是一种 4xx 客户端错误状态码，表示服务器无法处理当前请求，通常是因为请求内容的媒体类型或编码方式不符合服务端要求。常见表现包括 API 请求返回 415、网页表单提交失败、文件上传被拒绝等。
HTTP 415 与其他 HTTP 状态码虽然都可能导致请求失败，但对应的问题有所不同：
状态码 |
含义 |
主要问题 |
400 |
Bad Request |
请求语法或参数存在问题 |
403 |
Forbidden |
服务器拒绝访问请求 |
406 |
Not Acceptable |
服务器无法提供客户端可接受的响应格式 |
415 |
Unsupported Media Type |
请求提交的媒体类型或编码方式不受支持 |
与之前介绍的 HTTP 503 不同，503 通常表示服务器暂时无法处理请求，而 415 主要与请求内容格式有关。排查时应先判断错误类型，避免将请求格式问题误认为服务器故障。
二、触发 HTTP 415 的常见原因与场景
1. Content-Type 设置错误或请求体格式不匹配
Content-Type 用于声明请求正文的数据类型，如果请求头缺失、设置错误，或者声明的类型与实际提交的数据不一致，服务器就可能返回 415。
例如，接口要求接收 application/json，但客户端使用 application/x-www-form-urlencoded 提交表单数据；或者虽然声明为 JSON，实际发送的内容却不是合法的 JSON 格式。此时应检查请求头与实际请求体是否一致。
2. Content-Encoding 编码方式不受支持
Content-Encoding 用于说明请求内容采用的编码方式，例如 gzip、br 等。如果客户端使用了服务端不支持的编码方式，服务器可能无法正确解码请求内容，从而返回 415。可以检查请求头中的编码声明，并确认服务端是否支持对应的解码方式。
3. 服务端接口不支持当前媒体类型
不同 API 接口对请求格式有不同要求。例如，某个接口只接受 JSON 数据，但客户端提交了 XML 或其他格式，即使数据本身没有错误，也可能因为超出接口支持范围而被拒绝。遇到这种情况，需要查看 API 文档中的媒体类型要求，确认接口支持哪些格式。
4. 请求方式或接口配置不匹配
部分 API 会针对不同请求方法设置媒体类型限制。例如，POST、PUT 和 PATCH 接口可能分别定义了不同的请求格式。如果客户端调用方式与接口配置不一致，就可能触发请求错误。
需要注意，单纯使用了不被允许的请求方法，通常返回 HTTP 405（Method Not Allowed）；只有请求内容的媒体类型不符合接口要求时，才属于 HTTP 415 的排查范围。
三、实操指南：HTTP 415 错误如何排查与修复？
遇到 HTTP 415，不建议直接修改服务器配置，可以先从客户端请求入手，依次检查请求头、网络链路、请求体和接口配置。以下五个步骤可以帮助定位问题：
Step 1：检查请求头 Content-Type
首先打开浏览器开发者工具（F12），进入 Network 面板，找到返回 415 的请求，查看 Request Headers 中的 Content-Type，确认是否符合接口要求。
常见的媒体类型包括：
Content-Type |
适用场景 |
application/json |
JSON 数据提交 |
application/x-www-form-urlencoded |
表单键值对 |
multipart/form-data |
文件上传及表单数据 |
application/xml |
XML 数据 |
text/plain |
纯文本 |
例如，接口要求 JSON 格式，可以在请求头中设置：
Content-Type: application/json
如果使用 Postman 调试，可以进入 Body，选择 raw 和 JSON，让工具按照对应格式设置请求头。注意不要在使用 form-data 上传文件时，手动固定 multipart/form-data 的完整请求头，否则可能导致 boundary 参数缺失。
Step 2：检查网络环境与请求链路
如果相同的 API 请求在不同网络环境下返回结果不同，例如本地网络请求持续返回 415，但切换网络后能够正常响应，说明问题可能不只在请求格式，还可能与网络出口对应的网关策略或后端路由有关。
如果问题只在特定网络环境下出现，可以更换网络出口进行对照测试，保持请求地址、请求头和请求体不变，只调整网络出口，再次发送请求，观察返回状态是否发生变化：
- 更换出口后恢复正常：重点检查原网络出口对应的网关规则、请求转发及后端路由。
- 更换出口后仍返回 415：说明问题更可能出在请求媒体类型、请求体格式或服务端接口配置，应继续排查后续步骤。
需要注意的是网络出口不会直接改变请求的媒体类型，如果不同出口均返回 415，应优先回到请求格式和接口配置进行排查。
Step 3：检查请求体格式
确认请求头后，还需要检查实际提交的数据是否符合声明的媒体类型。例如，接口要求 JSON 格式，可以使用以下请求体：
{
"name": "test",
"status": "active"
}
在 Postman 中，检查 Body 是否选择了 raw → JSON。如果实际发送的是表单数据，却声明为 application/json，就需要调整请求体或请求头，使两者保持一致。
Step 4：检查 Content-Encoding
如果请求使用了压缩编码，需要检查请求头中的 Content-Encoding，确认客户端采用的编码方式是否受到服务端支持。
例如，请求使用了 gzip，但服务端不支持对应的解压方式，就可能导致 415。可以先取消不必要的请求压缩，重新发送请求；如果恢复正常，再检查客户端和服务端的编码配置。
Step 5：检查 API 接口支持的媒体类型
如果前面几步均未发现问题，就需要查看 API 接口文档及服务端配置。检查接口支持的请求方法、媒体类型和参数格式。例如，Spring Boot 项目可以检查接口上的 @PostMapping、consumes 等配置，确认是否限制了请求类型。如果接口只接受 JSON，可以参考以下配置：
@PostMapping(
value = "/api/data",
consumes = "application/json"
)
如果客户端提交的是其他格式，就需要根据接口要求调整请求内容，或者在服务端明确支持相应的媒体类型。
四、如何预防出现 HTTP 415？
1. 保持请求链路与运行环境稳定
如果 API 经过 Nginx、API Gateway 等中间层转发，需要检查请求头是否被意外覆盖或修改。例如，客户端发送 application/json，但网关转发时错误修改了 Content-Type，就可能导致后端接口无法正确解析请求。建议检查网关转发规则，确保 Content-Type、Content-Encoding 等请求头按照预期传递。
2. 统一客户端与服务端数据规范
对于经常调用的 API，可以在 Postman 中建立标准请求模板，统一请求方法、请求头和请求体格式，减少手动配置错误。例如，提交 JSON 数据时使用 Content-Type: application/json；上传文件时选择 multipart/form-data，并让 Postman 自动生成 boundary，避免手动配置错误。
3. 完善接口校验与测试机制
使用 Postman 或自动化测试工具，先验证接口能否正常接收 JSON、表单和文件等不同类型的数据。重点检查请求头是否正确、请求体结构是否符合要求，以及压缩编码是否受到服务端支持。同时，将接口支持的媒体类型、参数结构和请求示例写入文档，方便开发和调用人员按照统一规范配置。
五、FAQ
1. HTTP 415 是客户端问题还是服务器问题？
HTTP 415 属于 4xx 客户端错误，通常是请求内容不符合服务端要求。但如果服务端接口配置或媒体类型限制不合理，也需要检查后端设置。
2. Postman 请求为什么会返回 415？
常见原因是 Body 类型与 Content-Type 不匹配。例如，Body 选择了 form-data，却手动设置为 application/json。应检查 Body 类型和请求头，并按照接口文档重新配置。
3. 修改 Content-Type 就能解决 HTTP 415 吗？
不一定。修改前需要确认实际请求体格式和接口支持的媒体类型。如果只是修改请求头，却没有同步调整请求体，仍然可能返回 415。应确保请求头声明与实际提交的数据一致。
六、总结
HTTP 415 错误的核心在于请求内容与服务端接口要求不匹配。排查时，应从 Content-Type 和请求体格式入手，逐步检查内容编码、网络链路及接口配置。日常调用 API 时，规范请求格式、统一接口标准并做好测试验证，才能从源头减少此类错误。
