Unsupported Media Type

Server perspective

Use 415 when the request content type or content coding is not supported for this resource or method.

When to use

• •Return 415 for unsupported Content-Type values or unsupported request encodings
• •Use it when the server rejects the format of the incoming content, not the desired response format
• •Request Content-Type not supported
• •Sending XML to JSON-only endpoint
• •Incorrect file upload format
• •Missing or wrong Content-Type header

How to respond

• •Tell the client which media types or encodings are supported
• •Keep 415 distinct from 406, which is about the response representation

Headers to consider

• •Accept-Post — include this when the rejected request is a POST to advertise which media types the endpoint accepts.
• •No other status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

Response body

• •Include supported media types or encodings when the client can retry in another format.

Server-side pitfalls

• •Do not use 415 when the request body parsed fine but failed semantic validation
• •Do not use 415 for response-format negotiation problems
• •Response format negotiation (use 406 Not Acceptable)
• •Bad request structure (use 400 Bad Request)
• •Authentication required (use 401 Unauthorized)

Examples