HTTP status code

The HTTP 415 status code stands for "Unsupported Media Type". It is a client error response indicating that the server refuses to process the request because the media type of the request’s payload (usually specified in the Content-Type header) is not supported by the server for the targeted resource.

When is HTTP 415 Used?

• When the Content-Type of the request (which describes the type of data being sent, such as application/json, text/html, image/jpeg, etc.) is not supported by the server or the resource.
• It can occur when the client attempts to send data in a format that the server does not accept or cannot process.

Common Causes of HTTP 415 Errors

• Unsupported content types: The client sends a request with a Content-Type that the server is not equipped to handle.
• Wrong content type for the resource: The client sends a request with a Content-Type that is incompatible with the expected input type for the specific resource (e.g., sending XML data to an API endpoint that only accepts JSON).
• Missing or incorrect Content-Type header: Sometimes, the client does not provide a Content-Type header at all, or provides an incorrect one, making it unclear what kind of data is being sent.

Example Scenarios

• A client sends a POST request to upload an image with an unsupported content type like application/xml instead of the correct image/png or image/jpeg.
• A client sends JSON data to an API endpoint that only supports XML data.
• A client sends a form submission without specifying a Content-Type or with an invalid type like text/plain instead of application/x-www-form-urlencoded.

Example

Client Request (Unsupported Content-Type)

    
        POST /upload-image HTTP/1.1
        Host: example.com
        Content-Type: application/xml
        Content-Length: 1234

        <image><name>image1</name><data>...</data></image>
    

(The client attempts to upload an image, but the server expects image/png or image/jpeg, not application/xml.)

Server Response (415 Unsupported Media Type)

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

        {
          "error": "The server does not support the media type 'application/xml'. Please upload an image in a supported format."
        }
    

Best Practices for Handling HTTP 415

• Verify Content-Type: Ensure that the Content-Type specified in the request is appropriate for the data being sent and compatible with what the server expects.
• Documentation: Provide clear API documentation specifying the accepted media types for each endpoint so clients know what to send.
• Error Handling: Include clear error messages in the response that help the client understand why the content type is unsupported and provide guidance on what to send instead.
• Content Negotiation: Implement content negotiation mechanisms (e.g., Accept headers) that allow the server to specify what content types it can return, ensuring the client sends an acceptable one.

Summary

HTTP 415 means the media type (e.g., the format of the data in the request body) is not supported by the server for the resource being accessed. The client should check the Content-Type of the request and ensure it is compatible with what the server expects. To resolve this, the client must send the correct media type, as specified by the server or API documentation.