415 Unsupported Media Type

Usage

When the 415 Unsupported Media Type error message is received, the cause is often the Content-Type or Content-Encoding headers being rejected by the server. Alternatively, the server returns this error based upon further inspection of the message body.

In the latter case, the server indicates this error because parsing or recognizing the content failed. When the server recognizes the media type but does not support the format, 415 Unsupported Media Type is the most accurate response. When the content has structural errors, 400 or 422 are more appropriate.

This error is similar to 406, except 415 Unsupported Media Type is based on the Content-Type and Content-Encoding headers, rather than on the Accept header.

Example

The client wants to send a message in plain text, but the server sends 415 Unsupported Media Type because only HTML messages are accepted. The client subsequently changes the Content-Type header but leaves the original message intact. The server recognizes the body is not valid HTML and denies the request a second time.

Initial request

POST /blog/newmessage HTTP/1.1
Host: example.com
Content-Type: text/plain
Content-Length: 24

Good morning, Everybody!

Initial response, based on the Content-Type header

HTTP/1.1 415 Unsupported Media Type
Content-Type: text/html
Content-Length: 138

<html>
  <head>
    <title>Unsupported Format</title>
  </head>
  <body>
   <p>Please use HTML to post new messages.</p>
  </body>
</html>

Subsequent request attempting to bypass validation

POST /blog/newmessage HTTP/1.1
Host: example.com
Content-Type: text/html
Content-Length: 24

Good morning, Everybody!

Subsequent response, based on message body inspection

HTTP/1.1 415 Unsupported Media Type
Content-Type: text/html
Content-Length: 151

<html>
  <head>
    <title>Unsupported Format</title>
  </head>
  <body>
   <p>No HTML tags found. Use HTML to post messages.
   </p>
  </body>
</html>

How to fix

Verify the Content-Type header matches a format the server accepts. API documentation typically lists supported media types. Common values include application/json, application/xml, multipart/form-data, and application/x-www-form-urlencoded.

The body content must match the declared Content-Type. Sending plain text with Content-Type: application/json fails because the server attempts to parse the body as JSON. Some servers are strict about charset notation: charset=UTF8 instead of charset=UTF-8 triggers a rejection on certain platforms.

Check the Content-Encoding header when sending compressed data. A mismatch between the declared encoding (e.g. gzip) and the actual Compression format of the body produces a 415.

For file uploads, confirm the file type is in the server’s allow list. Servers often restrict uploads to specific formats like JPEG, PNG, or PDF.

Common mistakes in REST API clients:

Testing the request with a tool like Postman or curl isolates whether the issue is in application code or in the request itself. Postman sets the Content-Type header automatically when a body type is selected.

Code references

.NET

HttpStatusCode.UnsupportedMediaType

Rust

http::StatusCode::UNSUPPORTED_MEDIA_TYPE

Rails

:unsupported_media_type

http.StatusUnsupportedMediaType

Symfony

Response::HTTP_UNSUPPORTED_MEDIA_TYPE

Python3.5+

http.HTTPStatus.UNSUPPORTED_MEDIA_TYPE

Java

java.net.HttpURLConnection.HTTP_UNSUPPORTED_TYPE

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNSUPPORTED_MEDIA_TYPE

Angular

@angular/common/http/HttpStatusCode.UnsupportedMediaType