Unsupported Media Type
ActiveHTTP 415 Unsupported Media Type indicates the server refuses the request because the payload's format is not supported. Defined in RFC 9110 §15.5.16. Applies when the Content-Type or Content-Encoding of the request body is unacceptable. The response SHOULD indicate which media types are supported.
Description
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.
This status code is fundamentally about what the CLIENT SENDS. The server looked at either the Content-Type header or the actual payload bytes and determined it cannot process them. This is distinct from 406 Not Acceptable, which is about what the client is willing to RECEIVE (via Accept headers). 415 says 'I can't read what you gave me.' 406 says 'I can't give you what you want.'
The most common trigger is a missing or incorrect Content-Type header. APIs that strictly validate incoming content types will reject requests where the client sends `application/x-www-form-urlencoded` to an endpoint that only accepts `application/json`, or omits the Content-Type header entirely. Some frameworks auto-reject before the handler ever sees the request body.
The server SHOULD generate content that informs the client which media types are acceptable for the target resource in the current context. This might be communicated via an Accept header in the response, an Accept-Encoding header, or in the response body itself. This gives the client enough information to reformulate the request correctly.
A subtle but important case: 415 can also apply when the Content-Encoding is unsupported. If a client sends a request body compressed with Brotli but the server only supports gzip for request payloads, 415 is the correct response — the server cannot decode the content regardless of its media type.
Examples
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer token123
name=Alice+Smith&email=alice%40example.comHTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept: application/json
{"error": "unsupported_media_type", "message": "Content-Type 'application/x-www-form-urlencoded' is not supported. This endpoint accepts: application/json", "accepted_types": ["application/json", "application/json; charset=utf-8"]}POST /api/documents HTTP/1.1
Host: api.example.com
Authorization: Bearer token456
Content-Length: 42
{"title": "My Document", "body": "Hello"}HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept: application/json, application/xml
{"error": "unsupported_media_type", "message": "Content-Type header is required for requests with a body. Supported types: application/json, application/xml", "accepted_types": ["application/json", "application/xml"]}POST /api/images/upload HTTP/1.1
Host: api.example.com
Content-Type: image/tiff
Authorization: Bearer token789
Content-Length: 2048576
[binary TIFF data]HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept: image/jpeg, image/png, image/webp, image/gif
{"error": "unsupported_media_type", "message": "Image format 'image/tiff' is not supported. Please upload one of: JPEG, PNG, WebP, GIF.", "accepted_types": ["image/jpeg", "image/png", "image/webp", "image/gif"], "max_size_bytes": 10485760}Edge Cases
- •A missing Content-Type header on a POST/PUT/PATCH with a body is often treated as 415 by strict APIs — even if the body is valid JSON. The server cannot know the format without the header.
- •Content-Type with unsupported charset parameters (e.g., `application/json; charset=iso-8859-1`) may trigger 415 on servers that only accept UTF-8 encoded JSON.
- •415 can apply to Content-Encoding, not just Content-Type — if the client sends `Content-Encoding: br` (Brotli) but the server only supports gzip for request decompression, 415 is correct.
- •Some APIs return 415 when the Content-Type includes unexpected parameters (e.g., `application/json; boundary=something`) — the media type matches but the parameters make it unprocessable.
- •Multipart boundaries: sending `multipart/form-data` without a valid boundary parameter in the Content-Type header is technically a 415 case (malformed media type), though some servers return 400.
- •Browser form submissions default to `application/x-www-form-urlencoded` — API endpoints that only accept JSON will 415-reject direct form POSTs unless the frontend explicitly sets Content-Type.
- •PATCH requests with `application/json` may be rejected with 415 if the server expects `application/merge-patch+json` or `application/json-patch+json` — the media type IS the operation semantics.
When You'll See This
- →Client sends JSON body without setting Content-Type header
- →Frontend form POST hits an API endpoint that only accepts application/json
- →Uploading a .bmp image to an endpoint that only supports JPEG/PNG/WebP
- →Sending XML to a JSON-only REST API
- →PATCH request using application/json when the server requires application/merge-patch+json
- →Client sends a request body compressed with an unsupported Content-Encoding
- →API gateway rejects a request with Content-Type: text/plain before it reaches the backend
- →Mobile app sends protobuf-encoded body to an endpoint that only accepts JSON
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusUnsupportedMediaType |
| Rust | http::StatusCode::UNSUPPORTED_MEDIA_TYPE |
| Python | http.HTTPStatus.UNSUPPORTED_MEDIA_TYPE |
| Node.js | http.STATUS_CODES[415] |
| .NET | HttpStatusCode.UnsupportedMediaType |
| Java | HttpURLConnection.HTTP_UNSUPPORTED_TYPE |
| PHP | Response::HTTP_UNSUPPORTED_MEDIA_TYPE (Symfony) |
| Ruby | :unsupported_media_type (Rack) |
History
Introduced in HTTP/1.1 (RFC 2068, 1997) to handle the growing need for content negotiation in both directions. Carried forward unchanged into RFC 2616 (1999) and then RFC 9110 (2022). Became significantly more common with the rise of JSON-centric REST APIs that strictly validate Content-Type headers, rejecting form-encoded or XML submissions.
Related Status Codes
Related Headers
FAQ
What is the difference between 415 Unsupported Media Type and 406 Not Acceptable?
415 is about what the client SENDS — the server cannot process the request body's format (Content-Type or Content-Encoding). 406 is about what the client ACCEPTS — the server cannot produce a response in any format the client's Accept header lists. Think of it directionally: 415 = inbound content problem, 406 = outbound content problem. A request can be valid for 415 but trigger 406 simultaneously if the client sends JSON (accepted) but only accepts XML responses (not available).
Should I return 415 or 400 when the Content-Type header is missing?
Both are defensible, but 415 is more semantically precise. A missing Content-Type means the server cannot determine the media type of the payload — the format is effectively 'unsupported' because it's unknown. 400 Bad Request is broader and less informative. Best practice: return 415 with a response body explaining that Content-Type is required and listing accepted types. This gives the client actionable information to fix the request.
How should a 415 response indicate which media types are acceptable?
Three complementary approaches: (1) Include an Accept header in the response listing supported media types for that endpoint. (2) Include the list in the response body's error object (e.g., an 'accepted_types' array). (3) Document supported types in your API specification. The response body approach is most useful for programmatic clients because it's structured data they can parse and act on. The Accept header approach follows HTTP semantics more closely.