What Is a 415 Status Code? Causes, Fixes, and Best Practices

HTTP Error 415 Unsupported Media Type: The Complete Guide to Fixing Content-Type Mismatches

Quick answer: HTTP 415 error means “Unsupported Media Type”—the server is rejecting your request because the format of the data you’re sending doesn’t match what the server can accept.

If you’re working with APIs, web scraping, or proxy configurations, this error is frustratingly common. The good news? It’s usually easy to fix once you understand what’s happening under the hood.

This comprehensive guide covers everything: what error 415 means, real-world examples showing exactly how it appears, common causes, how it differs from other HTTP errors, and step-by-step solutions to get your requests working again.

---

What Does HTTP Error 415 Actually Mean?

HTTP 415 Unsupported Media Type is a client error status code indicating that the server refuses to accept the request because the payload format is in an unsupported format.

In plain English: You’re trying to send data to an API or server, but you’re sending it in a format the server wasn’t designed to handle. It’s like showing up at a restaurant that only serves Italian food with a detailed order for sushi—the kitchen simply can’t prepare what you’re asking for.

This error is particularly common when:

• Working with REST APIs that expect specific data formats (usually JSON or XML)
• Making POST, PUT, or PATCH requests that include a request body
• Using proxy servers that may modify or strip your headers
• Testing APIs with tools like Postman, cURL, or browser developer tools

---

What HTTP 415 Looks Like: Real Examples Across Different Tools

Seeing the error in context makes it much easier to diagnose. Here’s exactly how 415 errors appear in common scenarios:

Example 1: Postman – Content-Type Mismatch

Request:

text

POST /api/comments HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

{
  "user": "john",
  "comment": "This is a test comment"
}

Response:

text

HTTP/1.1 415 Unsupported Media Type
Date: Fri, 28 Jun 2024 12:00:00 GMT
Server: Apache/2.4.41 (Ubuntu)
Accept-Post: application/json; charset=UTF-8
Content-Length: 0

What’s happening: You’re sending JSON data but telling the server it’s URL-encoded form data. The server responds with 415 and helpfully includes an Accept-Post header showing exactly what format it does accept.

Example 2: cURL – Wrong Content-Type Header

Command:

bash

curl -X POST \
  -H "Content-Type: text/plain" \
  -d '{"name":"John","age":30}' \
  https://example.com/api/users

Response:

text

HTTP/1.1 415 Unsupported Media Type
Server: Apache/2.4.41 (Ubuntu)
Accept-Post: application/json; charset=UTF-8
Content-Length: 0

What’s happening: Your data is valid JSON, but your Content-Type header claims it’s plain text. The server sees the mismatch and rejects the request.

Example 3: Browser DevTools – Missing Content-Type

Request (missing header):

text

POST /api/comments HTTP/1.1
Host: example.com
Content-Length: 42

{"user":"jane","comment":"Missing content-type"}

Response:

text

HTTP/1.1 415 Unsupported Media Type
Date: Fri, 28 Jun 2024 12:00:00 GMT
Server: Apache/2.4.41 (Ubuntu)
Accept-Post: application/json; charset=UTF-8
Content-Length: 0

What’s happening: No Content-Type header means the server has to guess the format—and most APIs won’t guess. They’ll reject the request outright.

---

Common Causes of HTTP 415 Errors

Understanding why 415 errors happen is the first step to preventing them:

Cause	Description	Example
Wrong Content-Type Header	Header value doesn’t match actual data format	Sending JSON with Content-Type: text/html
Missing Content-Type Header	No header at all; server doesn’t guess formats	POST request with JSON body, no Content-Type
Payload-Header Mismatch	Data format differs from what header claims	XML data with Content-Type: application/json
Invalid JSON/XML Syntax	Malformed data even with correct headers	Missing comma in JSON, unclosed XML tags
Strict Server Validation	Server rejects minor variations (e.g., missing charset)	application/json vs application/json; charset=utf-8
Proxy Interference	Proxy modifies or strips your Content-Type header	Corporate proxy rewriting headers

---

HTTP 415 vs Other Status Codes: Critical Differences

Don’t confuse 415 with other common HTTP errors. Here’s how they differ:

Status Code	Meaning	When It Occurs	Key Difference
400 Bad Request	General syntax error	Malformed JSON, missing required fields	Problem with content structure, not format type
403 Forbidden	Authentication approved but access denied	Valid login but insufficient permissions	Authorization issue, not format issue
406 Not Acceptable	Server can’t respond in your requested format	Your Accept header requests unsupported response format	About response format, not request format
415 Unsupported Media Type	Request format not supported	Wrong/missing Content-Type, format mismatch	About request format specifically

Quick memory aid:

• 400 = “This JSON is broken”
• 403 = “You can’t be here”
• 406 = “I can’t send you what you asked for”
• 415 = “I can’t understand what you’re sending me”

---

How to Fix HTTP 415 Errors: Step-by-Step Solutions

Follow these steps to diagnose and resolve 415 errors:

1. Verify Your Content-Type Header

First, confirm you’re sending the correct Content-Type header for your data:

Data Format	Correct Content-Type
JSON	application/json
XML	application/xml or text/xml
Form Data	application/x-www-form-urlencoded
Multipart Form	multipart/form-data
Plain Text	text/plain
HTML	text/html

Pro tip: Many APIs also accept charset parameters: application/json; charset=utf-8

2. Check Your API Documentation

Every API specifies what formats it accepts. Look for:

• The Content-Type header the API expects
• Examples showing exact request formats
• Any special requirements (charset, formatting rules)

3. Validate Your Data Format

Even with the correct header, malformed data will cause problems:

For JSON:

json

// ✅ Valid JSON
{"name": "John", "age": 30}

// ❌ Invalid JSON (missing quotes)
{name: John, age: 30}

For XML:

xml

<!-- ✅ Valid XML -->
<user><name>John</name><age>30</age></user>

<!-- ❌ Invalid XML (unclosed tag) -->
<user><name>John<age>30</user>

Use online validators or IDE plugins to check your syntax.

4. Inspect the Accept-Post Header in Responses

When a server returns 415, it often includes helpful hints:

text

Accept-Post: application/json; charset=UTF-8, application/xml

This header tells you exactly what formats the server accepts for POST requests. Use it as your guide.

5. Test with Simple Tools First

Before debugging complex code, isolate the problem:

With cURL:

bash

# Test with correct JSON and header
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"test":"data"}' \
  https://example.com/api/test

With Postman:

1. Create a minimal request
2. Set the correct Content-Type header
3. Send simple, valid data
4. Gradually add complexity

6. Check for Proxy Interference

If you’re using proxies (especially corporate or datacenter proxies), they may modify your headers:

• Use our free proxy header test tool to see exactly what headers arrive at the destination
• Compare what you sent vs what the server received
• Consider using residential proxies that preserve header integrity

7. When to Call a Professional

If you’ve tried everything and still get 415 errors, consider:

• Consulting API documentation forums
• Hiring an API integration specialist
• Using API testing platforms with built-in debugging

---

Best Practices to Prevent HTTP 415 Errors

Prevention is better than debugging. Follow these guidelines:

✅ Always Set Content-Type Explicitly

Don’t rely on defaults. Always specify the exact Content-Type your API expects.

javascript

// Good practice
fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'John' })
});

✅ Validate Before Sending

Use schema validators to catch format issues before they hit the server.

✅ Check API Versioning

APIs change over time. A format that worked in v1 might not work in v2.

✅ Use API Clients with Built-in Validation

Tools like Postman, Insomnia, and Swagger UI can catch header issues before you send.

✅ Monitor API Changelogs

Stay informed about format requirements that might change with API updates.

✅ Test Headers Through Your Entire Stack

If you use proxies, load balancers, or CDNs, test the full request path.

---

HTTP 415 and Proxies: What You Need to Know

When you’re using proxies for web scraping, automation, or API integration, 415 errors can have unique causes:

Proxy-Specific Issues:

• Header Stripping: Some proxies remove Content-Type headers
• Header Modification: Proxies may normalize header case or values
• Protocol Downgrades: HTTP/2 to HTTP/1.1 conversion can affect headers
• Character Set Changes: Proxies might modify charset declarations

Solutions:

• Use residential proxies that maintain header integrity
• Test with proxy header checker tools
• Choose proxy providers that preserve original request formats
• Consider dedicated proxies for API work

---

Frequently Asked Questions About HTTP 415

Q: Can a 415 error be caused by the server, not my request?
A: Yes, but it’s rare. Sometimes servers have bugs or misconfigurations that reject valid formats. Check server logs if you have access.

Q: Does header case matter for Content-Type?
A: No—header names are case-insensitive. But header values must be exact (e.g., application/json not Application/JSON).

Q: Why do I get 415 with correct headers but malformed JSON?
A: The server attempts to parse your data based on the Content-Type. If parsing fails, it may return 415 (if it can’t determine format) or 400 (if it recognizes format but finds syntax errors).

Q: Can proxies cause 415 errors?
A: Absolutely. Proxies can modify or strip Content-Type headers, add unexpected headers, or change encoding. Always test through your full proxy chain.

Q: What’s the difference between 415 and 400?
A: 415 means “I don’t understand this format at all.” 400 means “I understand the format, but the content is broken.”

Q: How do I know what Content-Type an API expects?
A: Check the API documentation, look at the Accept-Post header in responses, or use an OPTIONS request to discover supported formats.

---

Summary: Mastering HTTP 415 Errors

HTTP 415 Unsupported Media Type errors are among the most straightforward HTTP status codes to fix—once you understand what they’re telling you.

Key takeaways:

• Always match your Content-Type header to your actual data format
• Validate your data syntax before sending
• Check API documentation for exact requirements
• Test through your entire stack, including proxies
• Use the server’s Accept-Post header as your guide

With the systematic approach outlined in this guide, you’ll diagnose and resolve 415 errors quickly, keeping your API integrations, web scraping projects, and automation workflows running smoothly.