HTTP 415 Unsupported Media Type: Causes and Fixes for APIs

APIs are picky by design. When a server receives a request, it needs to understand not only what you want to do, but also how the data is packaged. When that packaging does not match what the API expects, the result is often the frustrating but useful error: HTTP 415 Unsupported Media Type.

What Does HTTP 415 Unsupported Media Type Mean?

HTTP 415 Unsupported Media Type is a client error status code. It tells you that the server understood the request URL and method, but refused to process the request body because the media type is unsupported.

In simpler terms, the server is saying: “I received your request, but I do not know how to read the data you sent.”

This commonly happens in API requests that include a body, such as POST, PUT, or PATCH. These requests often send data in formats like JSON, XML, form data, or binary files. The server checks the Content-Type header to decide how to parse that data. If the header is missing, wrong, or unsupported, the server may return 415.

Common Causes of HTTP 415 Errors

Although the error sounds technical, the root cause is often very practical. Here are the most common reasons APIs return a 415 status code.

1. Incorrect Content-Type Header

The Content-Type header tells the server what kind of data is in the request body. If you send JSON, the header should usually be:

Content-Type: application/json

If you accidentally send:

Content-Type: text/plain

while the body contains JSON, the API may reject it. The body might be valid, but the label on the package is wrong.

2. Missing Content-Type Header

Some API clients or scripts omit the Content-Type header entirely. In that case, the server may not know whether the payload is JSON, XML, form data, or something else.

Some APIs try to guess the format, but well-designed APIs often avoid guessing because it can lead to security and processing issues. Instead, they return a clear 415 error.

3. Sending XML to a JSON-Only API

Many modern REST APIs accept only JSON. If you send XML to an endpoint that supports only application/json, the server can reject the request with 415.

• Expected: application/json
• Received: application/xml
• Result: HTTP 415 Unsupported Media Type

4. Confusing Content-Type and Accept Headers

Two headers are often mixed up:

• Content-Type: Describes the format of the data you are sending to the server.
• Accept: Describes the format you want the server to return.

For example, if you send JSON and expect JSON back, your headers may look like this:

Content-Type: application/json
Accept: application/json

If you only set Accept and forget Content-Type, the server may still reject the request body.

5. Multipart Uploads Without Proper Boundaries

File upload endpoints often use multipart/form-data. This media type requires a boundary parameter that separates each part of the form. Browser-based forms usually handle this automatically, but manually written API clients can get it wrong.

A correct multipart header may look something like:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryabc123

If the boundary is missing or malformed, the server may not be able to parse the uploaded file and may return 415.

How to Fix HTTP 415 Unsupported Media Type

The best way to solve a 415 error is to compare three things: the API documentation, your request headers, and your request body. If those three do not agree, you have likely found the problem.

Check the API Documentation

Start with the endpoint documentation. Look for sections labeled Request Body, Headers, Consumes, or Content-Type. These usually explain which media types the endpoint accepts.

For example, an endpoint might specify:

• application/json for standard JSON requests
• application/x-www-form-urlencoded for traditional form submissions
• multipart/form-data for file uploads

If your request uses anything else, update it to match the documented requirement.

Set the Correct Content-Type

If you are sending JSON, use this header:

Content-Type: application/json

And make sure the body is valid JSON:

{
  "name": "Ava",
  "email": "ava@example.com"
}

Do not send JSON-like text with single quotes or trailing commas, because strict JSON parsers may reject it:

{
  'name': 'Ava',
  'email': 'ava@example.com',
}

The second example is common in JavaScript-style objects, but it is not valid JSON.

Use the Right Format for Form Submissions

If an API expects form-encoded data, the request should use:

Content-Type: application/x-www-form-urlencoded

The body should look like this:

name=Ava&email=ava%40example.com

If the API expects JSON and you send form-encoded data instead, or the other way around, a 415 response is likely.

Let Your HTTP Client Handle Multipart Requests

When uploading files, avoid manually setting the multipart boundary unless you know exactly what you are doing. Many tools and libraries, such as browser fetch, Axios, Postman, and backend HTTP clients, can generate multipart boundaries automatically.

For example, when using FormData in a browser, it is often better not to manually set the Content-Type header. The browser will set it correctly, including the boundary.

Examples in Popular Tools

Using cURL

A correct JSON request with cURL looks like this:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name":"Ava","email":"ava@example.com"}'

If you remove the Content-Type header or change it to text/plain, the same endpoint may return 415.

Using JavaScript Fetch

fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    name: "Ava",
    email: "ava@example.com"
  })
});

The important detail is JSON.stringify. If you pass a raw JavaScript object as the body without converting it to JSON, your request will not be sent in the expected format.

Server-Side Reasons for 415 Errors

Not every 415 error is caused by the client. Sometimes the server is configured too narrowly or does not include the right parser middleware.

For example, in an Express.js application, JSON requests require middleware such as:

app.use(express.json());

Without it, the server may not parse JSON request bodies correctly. Similarly, APIs built with frameworks like Spring Boot, ASP.NET, Django, or FastAPI may need explicit configuration for supported request formats.

Server-side fixes may include:

• Enabling JSON body parsing
• Adding support for XML if required
• Configuring multipart upload handling
• Updating endpoint annotations or route definitions
• Returning clearer error messages for unsupported formats

How to Prevent HTTP 415 in API Integrations

The best fix is prevention. Teams can reduce 415 errors by making media type expectations obvious and testable.

• Document accepted media types for every endpoint.
• Validate requests early and return helpful error responses.
• Use API schemas such as OpenAPI to define request formats.
• Add integration tests for JSON, form data, and file uploads.
• Log request headers in development and staging environments.

A helpful 415 response should explain what went wrong. Instead of returning only Unsupported Media Type, an API might return:

{
  "error": "Unsupported Media Type",
  "message": "This endpoint accepts application/json only."
}

That small improvement can save developers minutes or even hours of debugging.

Final Thoughts

HTTP 415 Unsupported Media Type is not just an error message; it is a clue. It points directly to a mismatch between the request body, the headers, and what the API is prepared to process.

To fix it, check the Content-Type, verify the request body format, review the API documentation, and confirm that the server supports the media type you are sending. Once these pieces line up, the error usually disappears quickly. In API development, clear communication matters, and media types are one of the most important ways clients and servers agree on the conversation.