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|Editorial standard: source-backed technical guidance
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')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.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.