HTTP 415 Unsupported Media Type: Meaning and Fixes

Working with APIs or file uploads can sometimes result in a HTTP 415 Unsupported Media Type error. But there’s no need to get frustrated. The error has simple reasons behind it, and once you understand those, you’ll be able to fix it quickly.

We’ll explore what the HTTP 415 error means, why it occurs, and provide you with the exact steps to resolve it.

What Is HTTP 415 Error?

The HTTP 415 error is an HTTP status code that indicates the server has refused a request because the media type in the request is not supported. In simpler terms, the server didn’t understand your request because the format was wrong or there was a mismatch.

For example, if your request has a JSON body, but the server can only accept and understand XML, you’ll face a 415 Unsupported Media Type error.

There are similar 4xx HTTP error codes like the 403 Forbidden error or the 405 Method Not Allowed error , but they are entirely different from the 415 one. 403 is about permissions or lack thereof, 405 is about using the wrong HTTP method, and 415 is about media type and payload format.

It’s a good idea to double-check the error code before you go on looking for issues where they may not exist.

What Causes a 415 Error?

There are several main culprits behind the status code 415:

• Missing or incorrect Content-Type header. The Content-Type header informs the server what the format of the request body is, so it must be correct. Otherwise, you’ll get a 415 error.
• Mismatched content and payload type. If your Content-Type header indicates JSON, but the body is XML, that’s a mismatch and it results in an HTTP error. Make sure that if your header indicates JSON, the body also adheres to the same JSON structure.
• Unsupported file formats. If a server expects images in PNG or JPEG format, but receives an unsupported format, it will trigger the HTTP 415 error.

It’s not that difficult to prevent this error. All you need to do is make sure that your requests are properly written and you’re not using files that are not supported by the server.

Real-World Examples of HTTP 415 Error

When testing APIs with Postman or cURL, getting the HTTP 415 error is rather common. For example, the request below fails because JSON (-d flag) is being sent with an XML Content-Type (-H flag) header:

curl -X POST "https://api.example.com/upload" \
     -H "Content-Type: application/xml" \
     -d '{"name":"test"}'

Therefore, the server responds with an error:

{
  "error": "415 Unsupported Media Type",
  "message": "Expected application/json but received application/xml"
}

If you’re using Postman, a raw log may display this:

POST /upload HTTP/1.1  
415 unsupported media type  

In logs or browsers, it often looks like this:

Status code 415: Unsupported Media Type

These are a couple of many likely scenarios, but generally speaking, if you maintain the needed structure to your requests, you shouldn’t see too many of these errors. If you’re working with proxies, however, you may want to check out how to fix proxy error codes like 407, 502, and more .

How to Fix HTTP 415 Error (Step-by-Step)

Fixing the HTTP 415 error requires adjustments on either the client side or the server side.

Client-Side Fixes

• Setting the correct Content-Type header. Ensure that the declared media type matches the payload.
• Check file uploads. If you’re uploading, ensure that the formats are supported.
• Validate content encoding. Sometimes servers may expect a specific content encoding, such as UTF-8. Sending mismatched encoding can result in a 415 HTTP error.

Note: if you mismatch gzip content encoding with non gzip content encoding, you will usually receive a 400 or 406 HTTP status code.

Server-Side Fixes

1. Update server config to accept needed content. In frameworks like Express.js, use this:

app.use(express.json()); // Accept JSON
app.use(express.urlencoded({ extended: true })); // Accept form data

Without these, the server may give you the 415 Unsupported Media Type error.

2. Debug supported media types. In Spring Boot, for example, use this:

@PostMapping(value = "/data", consumes = "application/json")
public ResponseEntity saveData(@RequestBody MyData data) {
    return ResponseEntity.ok("Success");
}

If the client sends XML here, it leads to an HTTP 415 error.

3. Check content encoding setup. If the server rejects data, confirm that the required content encoding is enabled and handled properly.

If you manage both sides carefully, you can significantly reduce the chances of receiving an HTTP status code and ensure that the server doesn’t reject valid requests.

Conclusion

The HTTP 415 Unsupported Media Type error may seem complicated, especially if you’re a beginner, but the causes are often simple and easy to fix. In most cases, the issues arise from a mismatched Content-Type header, incorrect content encoding, or sending files in an unsupported format.

You can easily resolve the HTTP 415 error by aligning client requests with server expectations, or you can configure the server-side backend to accept the media type you’re sending.

If you’re interested in learning more about other HTTP errors, you may want to check out the 503 error , which means Service Unavailable and how to fix it.