415 Unsupported Media Type: what it means and how to fix it
A 415 means the server won't accept the format of your request body. Learn the usual Content-Type mistakes with curl, fetch and form uploads, and how to debug and return a clear 415.
· 6 min read · By the Spot Downtime team
415 Unsupported Media Type means the server refused the request because the format of the body is not one it accepts for that endpoint. The server read the request, looked at the Content-Type header (or sometimes the Content-Encoding), and decided it has no way to handle it.
It is almost always a client-side mistake, and almost always a one-line fix. It is also easy to confuse with 400 Bad Request and 422 Unprocessable Content, so the distinction is worth getting straight first.
415 vs 400 vs 422
- 415: the media type is wrong. The server would not even try to parse the body, for example because you sent
text/plainto an endpoint that only takes JSON. - 400: the type is acceptable but the body is malformed, such as JSON with a trailing comma.
- 422: the body parsed fine but a value failed validation, such as an email field that is not an email.
In practice, frameworks differ. Some return 400 for a missing content type, and some return 415 for a body they could not decode. Treat the status code as a hint and read the response body, which usually names the expected type.
The most common causes
1. Missing or wrong Content-Type on a JSON request
This is the classic. You send JSON, but the header says something else or nothing at all. With curl, -d defaults to application/x-www-form-urlencoded, so a JSON API rejects it:
# Fails with 415 on many JSON APIs
curl -X POST https://api.example.com/users \
-d '{"name":"Ada"}'
# Works
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Ada"}'The same thing happens with fetch. Passing a string body does not set a JSON content type for you:
// Sent as text/plain;charset=UTF-8 -> 415
fetch("/api/users", { method: "POST", body: JSON.stringify({ name: "Ada" }) });
// Correct
fetch("/api/users", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name: "Ada" }),
});2. Setting Content-Type by hand on a file upload
The reverse mistake. When you send a FormData object, the browser sets multipart/form-data; boundary=... itself. If you override the header with plain multipart/form-data, the boundary is missing and the server cannot parse the body, or rejects it. Leave the header out and let the client set it:
const form = new FormData();
form.append("file", fileInput.files[0]);
// No Content-Type header here
fetch("/api/upload", { method: "POST", body: form });With curl, use -F rather than -d and curl builds the multipart body and header for you.
3. The server only accepts specific types
Some endpoints are strict on purpose. A file upload endpoint may allow only image/png and image/jpeg. An API may accept application/json but not application/xml. Sending a .webp or a .heic to an endpoint with an allow-list gives you a 415. Check the API documentation for the accepted types, and convert the file if needed.
4. A charset or vendor type the server doesn't recognize
Some servers match the header literally. application/json; charset=utf-8 is valid and most frameworks accept it, but a hand-rolled matcher might not. Vendor types like application/vnd.api+json or application/merge-patch+json are only accepted where the API says so. A PATCH sent as application/json to an endpoint that requires merge-patch+json will fail.
5. Compressed request bodies
If you send Content-Encoding: gzip and the server or proxy does not decompress request bodies, it can answer 415. Most servers decompress responses but not requests by default. Either drop the compression or confirm the server supports it.
6. A proxy or WAF in front of the app
The 415 may not come from your application at all. API gateways and web application firewalls can enforce allowed content types before the request reaches your code. If the app logs show nothing, look at the gateway or WAF rules and logs.
How to debug it
- Read the response body. Many APIs say which media types they accept.
- Look at the headers you actually sent, not the ones you think you sent. In curl, use
-v. In the browser, open the Network tab and check the request headers. - Compare with a working request from the API docs or a tool like Postman, and diff the headers.
- Check that the method matches. A GET with a body, or a POST to a read-only route, can produce misleading errors.
- If you control the server, check which parsers are registered for the route and what they accept.
curl -v -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Ada"}' 2>&1 | grep -iE "^(> |< )"Returning a useful 415 from your own API
If you run the API, make the error easy to fix. Return 415 only for media-type problems, and say what you accept. The spec also allows an Accept header on the response, and Accept-Patch or Accept-Post when relevant, to list supported types.
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept-Post: application/json
{"error":"unsupported_media_type","message":"Send the body as application/json."}In Express, express.json() only parses requests whose type matches, and leaves req.body empty otherwise. Add an explicit check so clients get a clear error instead of a confusing validation failure:
app.post("/users", (req, res, next) => {
if (!req.is("application/json")) {
return res.status(415).json({ error: "Send the body as application/json." });
}
next();
});Don't guess the type
Catching 415s before users do
A 415 often appears after a client or gateway change: a new SDK version, a proxy that rewrites headers, or an API that tightened its parsing. A plain GET check will not catch it, because GET requests have no body. For APIs that matter, monitor a real POST with the right header and body, and assert on the status code and the response content. See how to monitor an API and how to set up multi-step API checks.
HTTP headers checkerSee the headers a URL returns, including content type and encoding.Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- HTTP errors · APIs428 Precondition Required: why the API wants If-Match and how to send itA 428 means the server refuses unconditional writes and requires headers like If-Match. How to read the ETag, send the condition and handle 412 in your client.November 15, 2026 · 6 min read
- HTTP errors · APIs412 Precondition Failed: If-Match, ETags and lost updatesA 412 means a conditional header such as If-Match or If-Unmodified-Since didn't hold. Why it happens, how to fix it in clients and servers, and how it differs from 409.November 14, 2026 · 7 min read