http error 415

The Role of the Content-Type Header

To understand the 415 error, you must be familiar with the Content-Type HTTP header. Whenever a client sends data to a server—whether it is submitting a form, uploading an image, or sending a JSON payload via an API—it must declare what format the data is in.

This is done using MIME types. Common examples include:

• application/json (for JSON API payloads)
• application/x-www-form-urlencoded (for standard HTML forms)
• multipart/form-data (for file uploads)
• image/png (for image files)

When the server receives the request, it looks at the Content-Type header. If the server is expecting application/json but the client sends a header declaring the payload is text/plain or application/xml, the server's parser will reject the data immediately and return a 415 error to prevent a crash or corrupted data parsing.

Common Causes of an HTTP 415 Error

Encountering a 415 Unsupported Media Type is almost always a developer or configuration issue, occurring predominantly during API integrations and file upload processes.

1. Missing or Incorrect Headers in API Requests

This is the most frequent cause in modern web development. A developer might write a script using `fetch()` or Axios to send a JSON object to a backend API. However, if they forget to explicitly set the header Content-Type: application/json, the HTTP client might default to text/plain. The strictly-typed backend framework (like Spring Boot, Express.js, or Laravel) sees `text/plain`, realizes its JSON parser cannot handle it, and throws a 415 error.

2. Uploading the Wrong File Extension

Many web applications enforce strict security rules regarding file uploads. If a web form is designed exclusively to accept profile pictures (expecting image/jpeg or image/png), and a user attempts to upload a malicious executable file (application/x-msdownload) or a PDF document, the server will block the upload and may return a 415 error indicating the media type is unacceptable.

3. Backend Framework Constraints

Some API endpoints are strictly configured by developers to only consume specific media types. If a developer sets an endpoint in their code to @Consumes("application/xml"), any request that isn't XML will be automatically rejected by the framework's routing layer with a 415 status code before it even reaches the business logic.

How to Fix an HTTP 415 Error

Troubleshooting this error requires inspecting the communication between the client and the server.

For Client-Side Developers

Open your browser's Network tab or your API testing tool (like Postman). Inspect the Request Headers of the failing call. Ensure that the Content-Type matches the exact format the API documentation requires. If you are sending a JSON string, ensure the header is explicitly set to application/json.

For Server-Side Developers

If you are building the API and clients are unexpectedly receiving 415 errors, check your endpoint routing configurations. Ensure your framework is configured to parse the incoming data correctly. For example, in Node.js (Express), if you expect JSON, you must ensure you have enabled the JSON middleware (app.use(express.json())) globally or on that specific route.

Frequently Asked Questions