415 Unsupported Media Type: What It Means and How to Fix It

What is a 415 Unsupported Media Type error?

If you’ve run into a 415 Unsupported Media Type error while working with an API, you’re seeing a mismatch between the data format you’re sending and the format the server expects. The server understands that a request arrived but refuses to process it because the payload format doesn’t align with the declared Content-Type.

A 415 is one of the most common early-stage integration errors. While the underlying fix is usually straightforward, such as correcting the header or payload and trying again, it often points to something deeper: outdated examples, inconsistent media types across environments, or drift between how an API was designed and how it’s being consumed. When multiple teams rely on the same API, or when automated systems and agents depend on predictable formatting, these small inconsistencies can slow development and create avoidable friction.

Example

You send JSON in the request body but forget to declare:

Content-Type: application/json

The server can’t correctly parse the incoming data and returns a 415.

How it’s different from similar errors

• 415 vs. 400 Bad RequestA 400 means the request is invalid in general. A 415 specifically means the media type is wrong or missing.

• 415 vs. 406 Not Acceptable415 is about the format you send.406 is about the format you ask to receive.

• 415 vs. 422 Unprocessable Entity415 → “I can’t parse this format.”422 → “The format is fine, but the data inside is invalid.”

Why 415 errors happen

Missing Content-Type header

This is the #1 cause. Without a Content-Type, the server has no way to infer how to parse your payload.

POST /users HTTP/1.1
Host: api.example.com

{ "name": "Petra" }

Incorrect Content-Type header

If your header says text/plain but your body is actually JSON, the server will reject it.

Unsupported media types

The endpoint may only accept JSON, but you send XML instead.

Mismatched character encoding

Some APIs require a specific charset (UTF-8 being the standard). If you send charset=ISO-8859-1, a strict API may reject it.

Malformed or empty request bodies

Even if the header is correct, a malformed payload can lead to parsing failures on strict servers.

Why these errors matter beyond the individual request

From a purely technical perspective, a 415 is easy to fix. But in practice, 415 errors are almost always symptoms of workflow issues, such as:

• Teams working from outdated examples

• API consumers receiving incomplete or ambiguous documentation

• Drift between API design, implementation, and testing (a common problem as teams and APIs scale)

• Automated systems or AI agents failing because the endpoint isn’t machine-readable

Media-type mismatches are unavoidable when your API artifacts, such as documentation, examples, tests, and schema, are not linked together. Strong teams avoid these by proactively removing opportunities for drift.

How to fix a 415 Unsupported Media Type error

Verify the Content-Type header

Match the header to the payload format.

JSON:

Content-Type: application/json

XML:

Content-Type: application/xml

Form URL-encoded:

Content-Type: application/x-www-form-urlencoded

Check the API documentation

Confirm which media types the endpoint supports. High-quality APIs explicitly define:

• Accepted Content-Type values

• Example request bodies

• Required encodings

• Unsupported formats

If documentation is sparse or inconsistent, it often leads directly to 415 errors.

Ensure the body matches the declared format

A common failure mode is “header says JSON, but body is actually text.”

Add charset when required

Most APIs assume UTF-8, but some specify others.

Content-Type: application/json; charset=utf-8

Test the request using a reliable API client

If you’re unsure whether the issue is in your application code or the request itself, testing with a client like Postman helps isolate the problem.

When you select a body type, such as JSON, form data, or XML, tools like Postman automatically set the correct Content-Type header, eliminating a major source of human error. When shared in a collection, that correct configuration propagates across your team, reducing inconsistent requests.

Common Content-Type values

Data format	Content-Type header
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
CSV	text/csv
Binary data	application/octet-stream

Troubleshooting checklist

If you’re debugging a 415:

• Confirm Content-Type is present

• Verify it matches the payload format

• Re-check API docs for allowed media types

• Validate body formatting (especially JSON)

• Test the request outside your application

• Verify encoding

• Ensure the endpoint supports your HTTP method

How teams avoid 415 errors long-term

Fixing an individual 415 is simple. Preventing them across multiple teams, or in an environment where several services depend on each other, requires more intention.

How high-performing teams avoid consistent 415s:

Use executable examples instead of static docs

When examples, tests, and requests are all part of the same collection or contract, they stay aligned. No one copies outdated cURL snippets from a wiki written six months ago.

Keep design, tests, and implementation connected

When collections, specs, and test suites share the same source, teams can update once and propagate everywhere. This prevents drift, which is the root cause of many 415s in growing organizations.

Provide consumers with clear, validated examples

If your API is intended for internal teams, partners, or an external developer audience, the quality of your examples directly affects how often they’ll hit media-type errors.

Ensure machine-readability for automated consumers and AI agents

AI systems, eval harnesses, and agents rely heavily on predictable content negotiation. Inconsistent or missing Content-Type values break automated consumers as easily as human ones.

What to do next

If you’ve corrected the header and still see a 415, it’s time to dig deeper:

• The server may reject specific formats entirely

• The endpoint may require additional headers

• There may be constraints tied to API versioning

• The body schema may be malformed even if the media type is correct

And if multiple people on your team are hitting 415s, that’s often a sign that your API documentation, examples, or design artifacts need to be brought back into alignment.