An HTTP 415 Unsupported Media Type response indicates that the origin server refuses to service the request because the payload is in a format not supported by this method on the target resource.

HTTP 415 at a glance

  • Status: 415
  • Phrase: Unsupported Media Type
  • Class: 4xx Client Error
  • Specification: RFC 9110 Section 15.5.16
  • Relevant request headers: Content-Type, Content-Encoding
  • Typical context: Sending XML or form data to a JSON-only REST endpoint
  • Client retry: Unsafe without adjusting the Content-Type header and payload format

What a 415 response tells you

When a client receives an HTTP 415 status code, specific protocol facts are established:

  1. The request payload format is unsupported: The server inspected the Content-Type or Content-Encoding header and determined that it does not have a parser or handler for that media format.
  2. The rejection occurs before payload parsing: The server rejects the request at the media type negotiation boundary, without attempting to parse the body content.
  3. Changing only the payload data will not fix the error: The issue resides in the media format declaration and serialization standard, not individual field values.

The critical distinction: 415 vs 406

Content negotiation in HTTP operates in two distinct directions:

[Request Payload Format]   ---> Content-Type ---> 415 Unsupported Media Type
[Response Desired Format]  ---> Accept       ---> 406 Not Acceptable
  • HTTP 415 (Unsupported Media Type): Concerns the request body sent by the client. The server cannot consume the format declared in Content-Type.
  • HTTP 406 (Not Acceptable): Concerns the response body requested by the client. The server cannot produce a representation matching the client’s Accept header.

What a 415 does not tell you

While an HTTP 415 confirms that the payload format is rejected, it does not mean:

  • The payload syntax is malformed (that would be 400 Bad Request).
  • The business validation rules failed (that would be 422 Unprocessable Content).
  • The endpoint does not exist (404 Not Found).
  • The HTTP method is disallowed (405 Method Not Allowed).

Similar status codes

400 Bad Request

The client sent a supported Content-Type (e.g., application/json), but the body contained syntax errors (unparseable JSON).

422 Unprocessable Content

The client sent a supported Content-Type with valid syntax, but business logic or validation rules failed.

406 Not Acceptable

The server cannot produce a response matching the format requested in the client’s Accept header.

For an overview of how headers dictate API processing, see our guide on The Content-Type Header and our comparison on HTTP 400 vs 422.

Diagnostic scenarios

Two common scenarios demonstrate how HTTP 415 errors occur in practice:

Scenario 1: Defaulting to text/plain or omitting Content-Type

A JavaScript client uses the standard fetch() API with a serialized JSON string body but forgets to specify the Content-Type: application/json header. The browser defaults the header to text/plain;charset=UTF-8. The backend framework rejects the request with HTTP 415 because it only accepts application/json.

Scenario 2: Legacy XML client communicating with modern JSON API

A legacy backend service or SOAP integration transmits XML payloads to a modern REST microservice. The microservice router inspects the incoming Content-Type: application/xml header, finds no XML deserializer registered, and responds with status 415.

Common causes of HTTP 415

Mismatched Content-Type header format

The client transmitted an unsupported Content-Type header (such as application/xml or text/plain) to an API endpoint that only accepts application/json.

Missing Content-Type header on requests with bodies

The client submitted an HTTP POST, PUT, or PATCH request containing a payload body without supplying a Content-Type header.

Unsupported Content-Encoding compression format

The client compressed the payload using an encoding algorithm (e.g., br, zstd, or gzip) that the origin server cannot decompress.

Incorrect charset or media type parameters

The client specified an unsupported media type parameter or character encoding (e.g., charset=iso-8859-1 instead of utf-8).

Headers you may encounter

  • Content-Type: In the response, describes the error representation (typically application/problem+json). In the request, must match the server’s expected MIME type.
  • Accept: May be consulted by the server to determine the error response format.
  • Accept-Encoding: Informs the client which compression algorithms the server supports for incoming payloads.

Troubleshooting flow

When troubleshooting an HTTP 415 error, follow this structured diagnostic path:

HTTP 415 Unsupported Media Type
  |
  +-- Did the client include a Content-Type header?
        |
        +-- No: Add 'Content-Type: application/json' (or appropriate MIME type).
        |
        +-- Yes: Compare the sent MIME type against API documentation.
              |
              +-- Is payload compressed (Content-Encoding)?
                    |
                    +-- Yes: Verify server supports decompression algorithm.
                    +-- No: Verify client serializes in the expected format.

What to check before changing backend code

Before modifying server-side media type parsers, check the request headers:

  1. Verify that the client explicitly sends Content-Type: application/json or the documented MIME type.
  2. Ensure client libraries (e.g., Axios, Fetch, curl) are not overriding or omitting headers.
  3. Check backend framework route annotations (e.g., @Consumes(MediaType.APPLICATION_JSON)).
  4. Verify if file upload endpoints require multipart/form-data with a valid boundary parameter.
  5. Check whether incoming requests include unsupported Content-Encoding headers.

How to verify the fix

Reproduce the request with curl by providing the correct Content-Type header:

curl -i -X POST https://api.example.test/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-token" \
  -d '{"productId": 942, "quantity": 2}'

Verify that the server accepts the payload and returns 200 OK or 201 Created.

Remediation paths to evaluate

If the client omitted or sent the wrong Content-Type

Update client request configuration to explicitly pass headers: { 'Content-Type': 'application/json' }.

If the server needs to support multiple media formats

Configure backend controllers or middleware to parse both JSON and XML (e.g., adding XML parser middleware in Express or Fastify).

If handling file uploads

Ensure frontend forms use multipart/form-data and allow browser HTTP clients to generate the multipart boundary string automatically.

FAQ

What is the difference between 415 and 400?

HTTP 415 means the server refuses to parse the format declared in Content-Type (e.g., XML sent to a JSON API). HTTP 400 means the server understands the format, but the data itself is malformed or invalid syntax (e.g., broken JSON).

What is the difference between 415 and 406?

HTTP 415 is triggered when the request body’s Content-Type is unsupported. HTTP 406 is triggered when the server cannot generate a response format that matches the client’s Accept header.

Should GET requests ever return 415?

Generally no. GET requests typically do not contain a request payload body, so there is no incoming media type to reject. Status 415 applies to methods with request payloads like POST, PUT, and PATCH.

Key takeaway

HTTP 415 Unsupported Media Type indicates that the server cannot accept or parse the payload format declared in the request’s Content-Type or Content-Encoding headers. Always verify that the client explicitly declares and serializes the exact MIME type required by the API specification.