415 Unsupported Media Type

This is an educational reference page about HTTP 415 Unsupported Media Type. The page itself is served as 200 OK so it can be indexed as HTTP documentation.

The server refuses the request because the content is in a format this method on the target resource does not support.

Specification

Registered in the IANA HTTP Status Code Registry as Unsupported Media Type. Defined in RFC 9110, Section 15.5.16.

What it means

HTTP 415 Unsupported Media Type means the server will not process the request body because of its format. The problem can come from the Content-Type header, the Content-Encoding header, or the server inspecting the data itself. RFC 9110 suggests an Accept response header to list the media types the server would accept, or Accept-Encoding for content codings.

When to use it

Return 415 when a JSON endpoint receives text/plain, form data, or no Content-Type at all.
Return 415 when the request uses a Content-Encoding, such as gzip or br, that the server does not accept.
Return 400 instead when the Content-Type is right but the body does not parse.

Common causes

A fetch() call that sends JSON.stringify(data) without setting Content-Type: application/json.
A form posted as multipart/form-data to an endpoint that only reads JSON.
An upload in an image format the service does not support, such as HEIC to a JPEG and PNG-only endpoint.

Headers involved

Content-Type on the request names the media type of the body.
Accept on the 415 response can list the media types the server would have accepted.
Accept-Encoding on the 415 response can list the content codings the server accepts.

How to fix it

Set Content-Type to match the body, such as application/json for JSON.
Convert the file to a supported format before uploading.
Remove Content-Encoding or use one the server lists in Accept-Encoding.

Examples

JSON sent without a JSON Content-Type

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: text/plain;charset=UTF-8

{
  "email": "ada@example.com"
}

HTTP/1.1 415 Unsupported Media Type
Accept: application/json
Content-Type: application/json

{
  "error": "Send the body as application/json."
}

Common mistakes

Using 415 for the wrong Accept header on the request. That is content negotiation of the response, and the code for it is 406 Not Acceptable.
Returning 400 without saying the media type is the problem.
Accepting any Content-Type and parsing the body as JSON anyway. Client bugs then show up as confusing validation errors.

Developer notes

406 and 415 mirror each other. 415 is about the request body the client sent. 406 is about the response format the client asked for in Accept.

Questions

What does HTTP 415 Unsupported Media Type mean?

HTTP 415 means the server will not accept the request body in its current format, usually because of the Content-Type or Content-Encoding.

How do I fix 415 when sending JSON?

Set the Content-Type request header to application/json and send a JSON body.

What is the difference between 415 and 406?

415 means the server cannot accept the format the client sent. 406 means the server cannot produce a format the client asked for.

Header and content rules

What RFC 9110 says about a 415 response, quoted from the RFC. The 4xx class rules also apply.

No keyword (server; Accept-Encoding): Use Accept-Encoding to list the codings that would have worked. RFC 9110 says "ought to", which is not a BCP 14 keyword. When: An unsupported content coding caused the 415. Table row
If the problem was caused by an unsupported content coding, the Accept-Encoding response header field (Section 12.5.3) ought to be used to indicate which (if any) content codings would have been accepted in the request. RFC 9110 §15.5.16
No keyword (server; Accept): Accept can list the media types that would have worked. Optional. When: An unsupported media type caused the 415. Table row
On the other hand, if the cause was an unsupported media type, the Accept response header field (Section 12.5.1) can be used to indicate which media types would have been accepted in the request. RFC 9110 §15.5.16

The same rules are in the response obligations table and its JSON.