415 - Unsupported Media Type
HTTP 415 Unsupported Media Type means request payload format is not supported for this method or resource.
Last reviewed: February 22, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Unsupported Media Type Mean?
The server reached the endpoint but refused to parse the body because payload media type or encoding does not match what this operation can consume.
Common Causes
- -Client posts protobuf bytes with Content-Type application/json, so server selects wrong decoder and rejects media type.
- -Multipart boundary token in header differs from actual body boundary emitted by custom uploader implementation.
- -PATCH endpoint accepts application/merge-patch+json only, and generic application/json payload is refused.
How to Fix Unsupported Media Type
- 1Set Content-Type to a media type explicitly supported by the endpoint.
- 2Ensure payload encoding matches the declared Content-Type value.
- 3Retest with a minimal sample body documented as supported.
Step-by-Step Diagnosis for Unsupported Media Type
- 1Capture request headers, raw payload sample, and parser error metadata from the failing path.
- 2Validate
Content-Type(including charset) against endpoint-specific media contracts. - 3Inspect gateway or SDK transformations that alter media type or payload encoding in transit.
- 4Retest with a minimal payload known to parse under the documented media type.
Media Type and Encoding Contract Audit
- -Verify declared
Content-Typematches actual wire encoding (example:application/jsonheader with URL-encoded form body). - -Check charset compatibility with server parser (example: endpoint expects UTF-8 JSON but client emits legacy charset).
Parser Capability and Endpoint Scope Checks
- -Confirm endpoint actually supports submitted format (example: JSON-only endpoint receives
multipart/form-data). - -Trace proxy/body-parser middleware ordering (example: gateway strips multipart boundary, causing origin parser rejection).
Implementation Examples
curl -i -X POST https://api.example.com/v1/uploads -H "Content-Type: text/plain" -d "raw text payload"
# Response:
# HTTP/1.1 415 Unsupported Media Type
# {"error":"Unsupported Media Type","code":"415"}const response = await fetch('https://api.example.com/v1/uploads', {
method: 'POST',
headers: { 'Content-Type': 'text/plain', 'Accept': 'application/json' },
body: JSON.stringify({ sample: true })
});
if (response.status === 415) {
console.error('Handle 415 Unsupported Media Type');
}import requests
response = requests.post(
'https://api.example.com/v1/uploads',
headers={'Accept': 'application/json', 'Content-Type': 'text/plain'},
json={'sample': True}
)
if response.status_code == 415:
print('Handle 415 Unsupported Media Type')Seen in Production
Mobile client sends form-encoded payload to JSON-only endpoint
Frequency: common
Example: App posts application/x-www-form-urlencoded body to endpoint that only accepts application/json.
Fix: Update client serializer and Content-Type defaults, then enforce contract checks in SDK integration tests.
Ingress middleware rewrites multipart requests incorrectly
Frequency: rare
Example: File upload path removes multipart boundary header at edge, leading to parser-level 415 at origin.
Fix: Fix proxy header forwarding and add raw multipart replay tests through the full edge-to-origin path.
Debugging Tools
- -curl -v with explicit Content-Type and payload samples
- -Raw request capture (mitmproxy or gateway tap logs)
- -Endpoint media-type contract tests
- -Parser middleware debug logs
How to Verify the Fix
- -Re-run requests and confirm 415 is replaced by successful parsing behavior.
- -Validate Content-Type and payload encoding consistency across all hops.
- -Confirm client SDKs now send only supported media types for this endpoint.
How to Prevent Recurrence
- -Publish accepted media types with concrete payload examples.
- -Add contract tests for unsupported Content-Type and malformed encodings.
- -Standardize serialization libraries to prevent content-type drift.
Pro Tip
- -generate negative test cases from your OpenAPI
requestBody.contentmap so every unsupported media type is rejected intentionally and consistently.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.