HTTP 415 – Unsupported Media Type

The HTTP 415 Unsupported Media Type status code indicates that the server refuses to process the request because the payload format (media type) is not supported. This typically occurs when the client sends data in a format (e.g., Content-Type) that the server cannot handle.

Key Points

The server does not support the media type specified in the Content-Type header of the request.
This status code is commonly used in APIs where the server expects data in a specific format (e.g., application/json) but receives it in an unsupported format (e.g., application/xml).
The server should include information in the response about the supported media types.

Common Causes

Incorrect Content-Type Header: The client sends a request with an unsupported or incorrect Content-Type header.
Server-Side Restrictions: The server is configured to accept only specific media types (e.g., JSON but not XML).
Misconfigured Client: The client application is sending data in the wrong format.

How to Fix

Client-Side Fix:

Ensure the Content-Type header in the request matches the format supported by the server (e.g., application/json).
Check the API documentation for the correct media type to use.
Convert the request payload to a supported format if necessary.

Server-Side Fix:

Return a 415 Unsupported Media Type status code with a clear error message.
Include an Accept header or response body detailing the supported media types.
Log unsupported media type errors for monitoring and debugging.

Example

If a client sends a request with Content-Type: application/xml but the server only supports application/json, the server might respond:

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

{
  "error": "Unsupported Media Type",
  "message": "The server does not support the 'application/xml' media type.",
  "supportedTypes": ["application/json"]
}

Client-Side Handling

Verify the Content-Type header in the request matches the server’s requirements.
Check the API documentation for supported media types.
Handle the 415 error gracefully by informing the user or retrying with the correct format.

Server-Side Handling

Return a 415 Unsupported Media Type status code when the request payload format is not supported.
Provide a list of supported media types in the response (e.g., using the Accept header or response body).
Log such errors for troubleshooting and improving server configuration.