415 Unsupported Media Type - What It Means & How to Fix

Q: What Content-Type should I use for JSON APIs?

Use 'Content-Type: application/json' for JSON request bodies. This is the standard for REST APIs. Make sure the body is valid JSON and the header is spelled correctly. Some APIs also accept 'application/json; charset=utf-8' which explicitly specifies the character encoding.

Q: Why do I get 415 when uploading files?

File uploads typically require 'Content-Type: multipart/form-data' with a boundary parameter. If you're sending the file as a raw binary body, use the file's actual MIME type (e.g., 'image/png', 'application/pdf'). Check the API docs for the expected format. Common mistake: sending form-urlencoded data when the server expects multipart.

Q: How is 415 different from 400 Bad Request?

415 Unsupported Media Type specifically means the Content-Type header value is not accepted by the server. 400 Bad Request is more general and usually means the request body itself is malformed or invalid. If the Content-Type is correct but the body content is wrong, you'll get 400. If the Content-Type header is wrong, you'll get 415.

ⓘ Quick Definition

The server is refusing to accept the request because the payload format (indicated by the Content-Type header) is not supported for the target resource. For example, sending XML to an endpoint that only accepts JSON, or posting form data when the API expects application/json.

⏰ When It Occurs

A 415 error occurs when the Content-Type header in your request doesn't match what the server expects. This is extremely common in API development, especially when switching between tools (Postman, curl, fetch) that set Content-Type differently by default.

The server understands the request, and the body might even be valid data, but it refuses to process it because the declared media type is not one it can handle for that endpoint.

⚠ Common Causes

Missing Content-Type header - Not including a Content-Type header at all on a POST/PUT request
Sending form-data instead of JSON - Using application/x-www-form-urlencoded when the API expects application/json
Wrong Content-Type for file uploads - Using application/json instead of multipart/form-data for file uploads
Typo in Content-Type value - Misspelling the media type (e.g., applicaiton/json)
Charset or encoding issues - Including an unsupported charset parameter that the server rejects
HTTP client overriding headers - Libraries like Axios or fetch automatically setting a different Content-Type than intended

Platform-Specific Notes:

Node.js Express requires explicit body parser middleware for each content type. Missing express.json() middleware causes 415 for JSON requests.

Nginx Does not generate 415 natively. Usually passed through from the application backend. Nginx doesn't parse request bodies by default.

Apache Can restrict accepted content types using mod_mime or application-level validation. PHP will attempt to parse most content types.

Cloudflare Passes Content-Type through to the origin. Workers can validate and reject unsupported media types before they reach your server.

🛠 How to Fix

Check API documentation - Look up which Content-Type values the endpoint accepts
Set the correct Content-Type header - Use application/json for JSON, multipart/form-data for file uploads
Ensure body matches Content-Type - If you declare JSON, make sure the body is valid JSON
Check for charset issues - Try removing or adding ; charset=utf-8 to the Content-Type
Verify HTTP client behavior - Some libraries auto-set Content-Type; check what's actually being sent with dev tools
Test with curl - Use curl -H "Content-Type: application/json" -d '{"key":"value"}' to isolate the issue

💻 HTTP Example

# Client sends form-urlencoded data to a JSON-only API
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

name=John&email=john@example.com

# Server Response (only accepts application/json)
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
Accept: application/json

{
  "error": "Unsupported Media Type",
  "message": "Content-Type 'application/x-www-form-urlencoded' is not supported. Use 'application/json'.",
  "accepted_types": ["application/json"],
  "statusCode": 415
}

🔗 Related Status Codes

Frequently Asked Questions

What Content-Type should I use for JSON APIs? +

Use Content-Type: application/json for JSON request bodies. This is the standard for REST APIs. Make sure the request body is valid JSON and the header is spelled correctly. Some APIs also accept application/json; charset=utf-8 which explicitly specifies UTF-8 encoding. When using JavaScript's fetch(), set it explicitly: headers: { 'Content-Type': 'application/json' }.

Why do I get 415 when uploading files? +

File uploads typically require Content-Type: multipart/form-data with a boundary parameter. If you're using a library like Axios or fetch with FormData, let the browser set the Content-Type automatically - don't set it manually, as it needs to include the boundary string. If the API expects raw binary upload, use the file's actual MIME type (e.g., image/png, application/pdf).

How is 415 different from 400 Bad Request? +

415 Unsupported Media Type specifically means the Content-Type header value is not accepted by the server - the format is wrong. 400 Bad Request is more general and usually means the request body itself is malformed, missing required fields, or has invalid data. If the Content-Type is correct but the body is invalid, you'll get 400. If the Content-Type header itself is wrong, you'll get 415.

Unsupported Media Type