415 Unsupported MediaType in Spring Application

1. Overview

In this tutorial, we’re going to showcase the causes and resolutions of the HTTP response code 415 Unsupported MediaType for POST requests in a Spring Application.

2. Backstory

One of our old business customers has asked us to design and develop a new desktop application for their product. The purpose of this application is to manage the users. We’ve never worked on this product before.

Since the timeline is tight, we’ve decided to use their existing set of backend APIs that was written a while ago. The challenge in front of us is that the documentation of these APIs is not very extensive. As a result, we’re only sure about the available API endpoints and their methods. So, we’ve decided not to touch the services – instead, we’ll start working on our application that will be consuming APIs from this service.

3. API Requests

Our application has started consuming the APIs. Let’s exercise the API to get all users:

curl -X GET https://baeldung.service.com/user

Hurrah! The API has responded back with a successful response. After that, let’s request an individual user:

curl -X GET https://baeldung.service.com/user/{user-id}

And let’s check the response:

{
    "id": 1,
    "name": "Jason",
    "age": 23,
    "address": "14th Street"
}

This seems to be working as well. Therefore, things are looking smooth. As per the response, we’re able to figure out that the user has the following parameters: id, name, age, and address.

Now, let’s try to add a new user:

curl -X POST -d '{"name":"Abdullah", "age":28, "address":"Apartment 2201"}' https://baeldung.service.com/user/

As a result, we’ve received an error response with HTTP status 415:

{
    "timestamp": "yyyy-MM-ddThh:mm:ss.SSS+00:00",
    "status": 415,
    "error": "Unsupported Media Type",
    "path": "/user/"
}

Before we figure out “Why are we getting this error?”, we need to look into “What is this error?”.

4. Status Code 415: Unsupported MediaType

According to the specification RFC 7231 title HTTP/1.1 Semantics and Content section 6.5.13:

The 415 (Unsupported Media Type) status code indicates that the origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource.

As the specification suggests, our chosen media type isn’t supported by the API. The reason for choosing JSON as the media type was because of the response from the GET requests. The response data format was in JSON. Hence, we assumed that the POST request would accept JSON as well. However, that assumption turned out to be wrong.

In order to find which format is supported by the API, we’ve decided to dig into the server-side backend code, and we find the API definition:

@PostMapping(value = "/", consumes = {"application/xml"})
void AddUser(@RequestBody User user)

This explains pretty clearly that the API will only support XML format. One may question here: What’s the purpose of this “consumes” element in Spring?

According to the Spring framework documentation, the purpose of the “consumes” element is:

Narrows the primary mapping by media types that can be consumed by the mapped handler. Consists of one or more media types one of which must match to the request Content-Type header

5. Resolution

There are two options in front of us to resolve the issue. The first option is to change the request payload format according to what the server expects. The second option is to update the API request so that it starts supporting JSON format.

5.1. Change Request’s Payload to XML

The first option is to send requests in XML format instead of JSON:

curl -X POST -d '<user><name>Abdullah</name><age>28</age><address>Apartment 2201</address></user>' https://baeldung.service.com/user/

Unfortunately, we get the same error as a result of the above request. If we remember, we had asked the question, what is the purpose of that “consumes” element in the API. That points us in the direction that one of our headers (“Content-Type“) is missing. Let’s send the request, this time with the missing header:

curl -X POST -H "Content-Type: application/xml" -d '<user><name>Abdullah</name><age>28</age><address>Apartment 2201</address></user>' https://baeldung.service.com/user/

This time, we received success in the response. However, we may encounter a situation where the client-side application is not able to send the request in the supported format. In that kind of scenario, we have to make changes on the server in order to make things relatively flexible.

5.2. Update the API on the Server

Suppose that our customer has decided to allow us to change the backend services. The second option as mentioned above is to update the API request to start accepting JSON format. There are three further options on how we can update the API request. Let’s explore each, one by one.

The first and most amateur option is to replace XML format with JSON on the API:

@PostMapping(value = "/", consumes = {"application/json"}) 
void AddUser(@RequestBody User user)

Let’s send the request again from our client-side application in JSON format:

curl -X POST -H "Content-Type: application/json" -d '{"name":"Abdullah", "age":28, "address":"Apartment 2201"} https://baeldung.service.com/user/'

The response will be a success. However, we’ll face a situation where all of our existing clients, who are sending requests in XML format, will now begin getting 415 Unsupported Media Type errors.

The second and somewhat easier option is to allow every format in the request payload:

@PostMapping(value = "/", consumes = {"*/*"}) 
void AddUser(@RequestBody User user

Upon request in JSON format, the response will be a success. However, the problem here is that it’s too flexible. We don’t want a wide range of formats to be allowed. This will result in inconsistent behavior in the overall codebase (both client-side and server-side).

The third and recommended option is to add specifically those formats that the client-side applications are currently using. Since the API already supports the XML format, we’ll keep it there as there are existing client-side applications sending XML to the API. To make the API support our application format as well, we’ll make a simple API code change:

@PostMapping(value = "/", consumes = {"application/xml","application/json"}) 
void AddUser(@RequestBody User user

Upon sending our request in JSON format, the response will be a success. This is the recommended method in this particular scenario.

6. Conclusion

In this article, we’ve learned that the “Content-Type” header must be sent from the client-side application request in order to avoid the 415 Unsupported Media Type error. Also, the RFC explains clearly that the “Content-Type” header of the client-side application and server-side application must be in sync in order to avoid this error while sending a POST request.