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

What this error means & how to recognize it

• An API client, browser form, upload tool, monitoring check or application reports 415 Unsupported Media Type.
• The response may affect one endpoint, HTTP method or request format while other pages and routes continue to work.
• A request may fail after changing the body format, Content-Type, content encoding, upload type or client library.
• Response headers may reveal the server, proxy or CDN that generated the response, along with caching, authentication, redirect or rate-limit context.
• DNS resolution and TLS negotiation may succeed because an HTTP response was received; those checks do not prove that the request content was acceptable.

Root causes, ordered by likelihood

1. Unsupported request media type: The endpoint does not accept the value sent in Content-Type, such as sending form data to a route that accepts JSON only.
2. Incorrect or missing request header: The client omits Content-Type, sends a typo, or labels the body differently from its actual format.
3. Unsupported content encoding: The request uses a compression or transfer encoding that the receiving component cannot process.
4. Wrong endpoint or method: A request is sent to a route that expects a different representation, upload format or HTTP method.
5. Proxy, CDN, WAF or web-server validation: An intermediary rejects the request before it reaches the application, or applies rules that differ from the application’s documented requirements.
6. Recent application or configuration change: A deployment, routing change, parser update, authentication integration or proxy rule changes which request formats are accepted.

The status code alone does not identify the responsible component. Confirm the request details and matching logs before treating authentication, permissions, limits or upstream configuration as the cause.

How to fix it

For visitors and non-technical users

1. Retry the exact action once. Confirm the URL and, if applicable, the upload or form action you selected. Avoid repeatedly submitting the same request.
2. Use the normal sign-in flow. If the endpoint requires an account, sign in through the site’s regular interface rather than manually changing request headers or cookies.
3. Check the submitted file or content. If the error occurs during an upload or form submission, use the format requested by the site and avoid renaming a file without converting it.
4. Try the site’s supported interface. If an API tool, browser extension or custom integration fails, compare it with the site’s normal web form or application.
5. Contact the site owner if it persists. Include the affected URL or feature, approximate time, HTTP 415 result and the action that failed. Do not send passwords, cookies, authorization tokens or private file contents.

For developers and API clients

1. Capture the complete request shape. Record the method, URL path, query parameters, Content-Type, content encoding, relevant Accept value and a sanitized description of the body. Do not log secrets or personal data unnecessarily.
2. Compare the request with the endpoint contract. Verify that the route and method accept the representation being sent. For example, confirm whether the endpoint expects JSON, form-encoded data, multipart form data, XML or a particular upload format.
3. Make the declaration match the body. Do not label form data as JSON or send a compressed body without the corresponding supported encoding. Let the client library construct multipart boundaries when it provides that feature.
4. Use a minimal reproduction. Remove optional fields and unrelated middleware where possible, then repeat the same request with a known-supported body. Preserve the original request for comparison.
5. Inspect the response. Check status, Content-Type, caching indicators, server or proxy identifiers, redirects and any error body. A response generated by a gateway may not reflect the application’s own validation.
6. Check logs at the responsible layer. Match the request timestamp, route and correlation or request identifier against application, web-server, reverse-proxy, CDN or WAF logs.
7. Apply the narrowest fix. Correct the client header, serializer, upload format, route contract or narrowly scoped intermediary rule. Do not broadly disable validation, authentication or security filtering as a first response.
8. Retest and check adjacent behavior. Repeat the original request, then test the same endpoint with its supported formats and verify that related routes still return their intended status codes.

For site owners and operators

1. Reproduce the failure from the same client type and request method, capturing sanitized headers and timing.
2. Determine whether the 415 was generated by the application, web server, reverse proxy, CDN or WAF by comparing response headers and logs at each layer.
3. Review recent deployments and changes to routing, request parsing, upload handling, proxy forwarding, content encoding and security rules.
4. Confirm that caches or intermediaries are not serving an inappropriate stored response for the request.
5. Correct the specific route or client contract, document accepted formats, and retain enough logs to confirm the fix.
6. If the request is intentionally unsupported, ensure the endpoint behavior and client-facing documentation make the accepted format clear.

Prevention & how to verify the fix

• Document the accepted HTTP methods, media types, encodings and upload formats for each important endpoint.
• Use automated tests for representative JSON, form, multipart and other supported request types after application or proxy changes.
• Keep routing, request parsing, proxy, CDN and WAF configuration under version control with reviewable changes.
• Monitor status codes by route and method rather than treating all 4xx responses as one category.
• Keep correlation IDs and appropriately sanitized application and intermediary logs available for the relevant retention period.
• Make client integrations fail clearly when the server’s accepted media types change, and test them against the documented contract.

Frequently asked questions