415 Unsupported Media Type

Description

The 415 Unsupported Media Type status code indicates that the server refuses to accept the request because the payload format is in a format not supported by the server for the requested method. 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 commonly used when: - A client sends a request with a Content-Type that the server doesn't support - A client sends data in a format that doesn't match the specified Content-Type - A client uses a Content-Encoding that the server doesn't support - The server only accepts specific formats for certain operations

The 415 Unsupported Media Type status helps APIs and web services maintain data integrity by rejecting content in formats they aren't designed to process.

Syntax

The server responds with a 415 Unsupported Media Type status:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Unsupported Media Type",
  "message": "The server does not support the request payload format"
}

Examples

Unsupported Content-Type Example

A client sends a request with an unsupported Content-Type:

Client Request:

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/xml
Content-Length: 162

<user>
  <name>John Doe</name>
  <email>[email protected]</email>
  <role>admin</role>
</user>

Server Response:

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

{
  "error": "Unsupported Media Type",
  "message": "The API does not support XML. Please use JSON instead.",
  "supported_types": ["application/json"],
  "documentation": "https://api.example.com/docs/formats"
}

Mismatched Content Format Example

A client specifies a JSON Content-Type but sends data in a different format:

Client Request:

POST /api/data HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 28

name=John&email=john@example.com

Server Response:

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

{
  "error": "Unsupported Media Type",
  "message": "Content-Type is application/json but the request body is not valid JSON",
  "suggestion": "Check your request body format"
}

Unsupported Content-Encoding Example

A client uses a compression encoding that the server doesn't support:

Client Request:

POST /api/documents HTTP/1.1
Host: docs.example.com
Content-Type: application/json
Content-Encoding: br
Content-Length: 156

[Brotli-compressed JSON data]

Server Response:

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

{
  "error": "Unsupported Media Type",
  "message": "The server does not support Brotli compression",
  "supported_encodings": ["gzip", "deflate"],
  "suggestion": "Please use one of the supported content encodings"
}

Summary

The 415 Unsupported Media Type status code is an important tool for servers to communicate format compatibility requirements to clients. It helps maintain data integrity by ensuring that servers only process content in formats they're designed to handle. This status code is particularly valuable for APIs that support specific data formats or have strict requirements about how data should be structured and encoded. By providing information about supported formats, servers can guide clients toward making compatible requests.