HTTP status code for unaccepted Content-Type in request

Question

For certain resources, my RESTful server only accepts PUT and POST requests with JSON objects as the content body, thus requiring a Content-Type of application/json instead of application/x-www-form-urlencoded or multipart/form-data or anything else.

Malformed JSON (or lack thereof) returns a 400 with the error message taken directly from the exception raised by the JSON parser, for debugging purposes.

Which HTTP error code means that the client sent a request with an unacceptable Content-Type, even if the server could technically parse the request content?

Weizmann

See here for a definitive answer: #19418053 – Leonoreleonsis

Your server couldn't technically parse the content if the Content-Type was incorrect: how would it know for sure how to parse it? – Iridic

@Iridic - i assume that for certain endpoints the server expects the payload in the body to be of a certain type. For example each POST request to /my/best/endpoint/ever is expected to have a body with a valid json object. – Manichaeism

@Manichaeism In theory the server could ignore the Content-Type header, but that would be incorrect behavior that doesn’t adhere to what the RFC dictates. Sounds like something Microsoft would do, and anyone who remembers the era of Internet Explorer 3 and 4 will agree that that’s a bad thing. (Microsoft has a history of preferring file extensions over MIME types; but that’s not how the internet works: the internet doesn’t run on Windows, and file extensions mean very little). – Iridic

Answer 1

It could be 415 Unsupported Media Type according to this list: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16.

3rd party edit

From the current RFC9110 HTTP Semantics

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

The format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.

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.

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.

Source RFC9110 - 415 unsupported media type

Opine

I'm still wondering if there a difference between "unnaccepted content type" and "unsupported media type" -- where the actual content (potentially different from the declared content) does not match with what is intended. – Hoop

415 is correct, but you shouldn't use RFC 2616; it has been obsoleted by RFC 7231. – Disorient

415 Unsupported Media Type means the client has provided data in a format that the server doesn't support (as indicated by the request's Content-Type header). For example, trying to do a POST request to create record of type User with the resource in format application/xml but the server can't process XML requests for that resource type. 406 Not Acceptable means the incoming request is wanting the response data in a specific format (as indicated by the Accept header) which the server can't provide (for example, wanting a record as XML when the server only provides JSON). – Clotilde

careful parsing of the language of 7231 (2616 is superseded) says otherwise "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. The format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly." - read that carefully. 415 is widely regarded (not correctly IMO) as appropriate but it is not. Convenient use is 1 thing; provable correctness is another – Cressida

Content without a content type is basically meaningless. So the distinction that @Hoop and @Cressida seem to want to make between the two doesn't exist. If you get a Content-Type header that indicates a media type you don't accept, 415 Unsupported Media Type is absolutely the correct response. If you get content with no Content-Type header, then you should reject the request outright because you would have no definitive way to know how to parse the content. – Iridic

@Iridic When you say "reject the request outright" what response code would you send? 415? – Amorphism

Good question. I guess a blanket 400 Bad Request would be ok. RFC 7231 says: “The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).” That seems applicable in that case. Alternatively, the RFC says you MAY assume application/octet-stream if there is no Content-Type header, so then if that is a content type your service doesn’t support, 415 Unsupported Media Type would apply. – Iridic