What 415 Unsupported Media Type actually means

A 415 Unsupported Media Type response is not the same as a broken URL, missing route, invalid token, or server crash. It usually means the server reached the part of the request where it looked at the body format and decided, “I do not accept this format here.”

Think of the API endpoint as a door with a label. The label might say:

This endpoint accepts:
Content-Type: application/json

Expected body:
{
  "email": "student@example.com",
  "password": "example-password"
}

If your client sends text/plain, application/x-www-form-urlencoded, multipart/form-data, an empty body, or a JavaScript object that was not converted to JSON, the server may reject it with 415.

The biggest beginner mistake is treating 415 like a general API failure. It is more specific than that. It points to the packaging of the request body. The server may be saying, “I expected JSON, but you sent something else,” or “You said this is JSON, but the body is not valid JSON.”

Content-Type vs Accept: the header mix-up behind many 415 errors

Two headers often get mixed up: Content-Type and Accept. They sound similar, but they point in opposite directions.

For most beginner JSON API calls, this is the safe starting point:

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

But they do not mean the same thing. If you send JSON, use Content-Type: application/json. If you want JSON back, use Accept: application/json. A 415 usually points to the sending side, not the response side. A 406 usually points to the response format the client asked for.

Common reasons your JSON API returns 415

Most 415 errors come from one of these practical mistakes. The exact framework may be different, but the pattern is usually the same.

The fastest way to narrow it down is to compare the exact working request from Postman or cURL with the failing browser request in DevTools. Do not compare what you think you sent. Compare the actual headers and actual payload.

The safest debugging order for a 415 error

When 415 appears, beginners often change random pieces of the request. They switch fetch to Axios, remove headers, add CORS settings, change the URL, or rewrite the backend route. That makes the problem harder. Use this order instead.

Correct examples for JSON API requests

Correct fetch request with JSON

This is the basic browser fetch pattern for sending JSON:

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    name: "Sagar",
    email: "sagar@example.com"
  })
});

const data = await response.json();

if (!response.ok) {
  console.error("API error:", response.status, data);
}

The important pair is Content-Type: application/json plus JSON.stringify(). One without the other often creates confusing behavior.

Wrong fetch request that can cause 415

This request looks innocent, but it is wrong because the body is a JavaScript object, not a JSON string:

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: {
    name: "Sagar",
    email: "sagar@example.com"
  }
});

Depending on the environment, the server may receive an invalid body, an empty body, or a body that does not match the declared media type.

Correct Axios request with JSON

Axios usually serializes plain objects as JSON when used normally, but it is still helpful to be explicit when debugging:

const response = await axios.post(
  "https://api.example.com/v1/users",
  {
    name: "Sagar",
    email: "sagar@example.com"
  },
  {
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json"
    }
  }
);

Correct cURL request with JSON

A clear cURL request is useful because it removes browser and frontend framework confusion:

curl -i -X POST "https://api.example.com/v1/users" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{"name":"Sagar","email":"sagar@example.com"}'

Postman settings to check

In Postman, a JSON request should usually use:

• Method: POST, PUT, or PATCH depending on the endpoint.
• Body tab: raw.
• Format dropdown: JSON.
• Header: Content-Type: application/json.
• Optional response preference: Accept: application/json.

When the API does not want JSON

Not every request body should be JSON. A file upload endpoint, OAuth token endpoint, legacy PHP endpoint, or regular HTML form endpoint may expect a different format. If you force JSON into an endpoint that expects form data, a 415 response may be correct.

Form URL encoded request

Some endpoints expect application/x-www-form-urlencoded:

const params = new URLSearchParams();
params.append("email", "sagar@example.com");
params.append("password", "example-password");

const response = await fetch("https://api.example.com/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "application/json"
  },
  body: params.toString()
});

Multipart FormData request

For file uploads, use FormData. Do not manually set the multipart boundary:

const formData = new FormData();
formData.append("avatar", fileInput.files[0]);
formData.append("name", "Sagar");

const response = await fetch("https://api.example.com/profile/avatar", {
  method: "POST",
  body: formData
});

When using browser FormData, the browser sets the correct multipart Content-Type with a boundary. If you manually set only multipart/form-data, the server may not be able to parse the upload correctly.

Backend parser mistakes that create 415 errors

Sometimes the frontend is correct, but the backend is not ready to accept the media type. The route exists, the method is correct, and the body is valid, but the framework parser is missing or too strict.

Express and Node.js

In Express, JSON body parsing must be enabled before routes that need req.body:

import express from "express";

const app = express();

app.use(express.json());

app.post("/users", (req, res) => {
  res.json({
    received: req.body
  });
});

If the client sends JSON but the server does not parse JSON, you may see empty bodies, validation failures, or media type errors depending on the middleware and route logic.

Laravel

Laravel can handle JSON requests, but your route, validation, middleware, and client headers still need to line up. A typical client request should include:

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

If Laravel returns HTML error pages instead of JSON during API debugging, check your Accept header and route group. API clients usually expect JSON responses, not browser-style HTML error pages.

Spring Boot

Spring Boot endpoints can reject a body if the consumes media type does not match the request:

@PostMapping(
  value = "/users",
  consumes = "application/json",
  produces = "application/json"
)
public User createUser(@RequestBody User user) {
  return userService.create(user);
}

If the endpoint consumes JSON and the client sends form data or text, 415 is a reasonable response.

Django REST Framework

In Django REST Framework, parser configuration controls which request body types the API accepts. If a view only allows JSON parsing, form or multipart requests may be rejected. If a view expects multipart uploads, JSON may be the wrong format.

Plain PHP

In plain PHP, JSON request bodies do not automatically appear in $_POST. You usually need to read the raw input and decode JSON:

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);

if (json_last_error() !== JSON_ERROR_NONE) {
  http_response_code(400);
  echo json_encode(array(
    'error' => 'invalid_json',
    'message' => 'Request body must be valid JSON.'
  ));
  exit;
}

If a PHP project expects $_POST, it may actually be expecting form data, not JSON. That is a common issue in student projects and older downloaded PHP/MySQL projects.

Why 415 sometimes appears with CORS errors

A JSON request from a browser can trigger CORS preflight because of the method, headers, or body type. That means you may see both CORS and 415 while debugging the same feature.

Example browser preflight:

OPTIONS /v1/users HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

The server should allow the requested header and method:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

If OPTIONS fails, your real request may not run. If OPTIONS succeeds and the real POST returns 415, then the CORS layer is probably okay and the body format layer is the next issue.

WordPress and PHP API notes

WordPress users run into 415 errors in two common ways: calling an external API from a Custom HTML block or calling an API from PHP using the WordPress HTTP API. The fix depends on where the request is being made.

Browser JavaScript inside WordPress

If a Custom HTML block contains JavaScript that calls an API, it runs in the visitor’s browser. That means CORS, browser headers, and frontend request formatting matter:

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

Server-side WordPress request

If you call the API from PHP, use the correct headers and encode the body:

$response = wp_remote_post('https://api.example.com/v1/subscribe', array(
  'headers' => array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
  ),
  'body' => wp_json_encode(array(
    'email' => 'reader@example.com',
  )),
  'timeout' => 20,
));

Do not pass a PHP array as the body while also saying it is JSON unless your code actually JSON-encodes it. The body format and the header must agree.

Bad fixes that make 415 harder to debug

Copyable 415 debugging checklist

Use this note when asking a teammate, instructor, API provider, or support team for help. It forces you to collect the details that usually reveal the problem.

415 Unsupported Media Type debugging note

Endpoint:
Example: https://api.example.com/v1/users

Method:
POST / PUT / PATCH

Expected request body format from docs:
JSON / form-urlencoded / multipart / text / vendor media type

Actual Content-Type sent:
Example: application/json

Actual Accept sent:
Example: application/json

Actual request body:
Paste sanitized body here.

Client used:
Postman / cURL / fetch / Axios / PHP / WordPress / mobile app

Does it work in Postman?
Yes / No

Does it work in cURL?
Yes / No

Does it fail in browser?
Yes / No

Browser Network tab:
OPTIONS status:
Real request status:
Console error:

Backend/framework:
Express / Laravel / Django / Spring Boot / WordPress / PHP / other

Parser/middleware enabled:
JSON parser:
Form parser:
Multipart parser:

What changed recently:
New endpoint / new frontend / new hosting / proxy / CORS change / auth change / API version change

Most likely issue:
Missing Content-Type / wrong Content-Type / body not stringified / endpoint expects form data / backend parser missing / CORS preflight failing

Related CodeZips tools for this problem

Use these CodeZips tools when you want to turn the error into a clean debugging checklist, request example, or support note.

Technical references used for this guide

This article is written as a practical beginner debugging workflow, with status-code and header behavior checked against web platform documentation.

• MDN Web Docs: 415 Unsupported Media Type
• MDN Web Docs: Content-Type header
• MDN Web Docs: Accept header
• MDN Web Docs: 406 Not Acceptable
• MDN Web Docs: Media types / MIME types
• MDN Web Docs: Cross-Origin Resource Sharing