Error Code 415: Quick Fixes for Unsupported Media Type

You've got a deployment waiting, the payload looks right in Postman, and production still throws error code 415. That's the kind of failure that eats an afternoon because the request “works” in one place and dies in another, usually at the point where a gateway, parser, or automation client disagrees about what the body is.

If you need a quick pattern to keep the rollback from spiraling, use Server Scheduler to keep non-production systems consistent while you debug. Stable environments make 415s easier to reproduce, and reproductions are what save hours.

Meta title: Error Code 415 Unsupported Media Type Fixes
Meta description: Practical fixes for error code 415, from Content-Type and Content-Encoding mismatches to gateway rejections and automation fingerprinting in production.
Author: Server Scheduler Staff
Reading time: 6 min

What Error Code 415 Actually Means

A new API integration can look clean in testing, then fall apart the moment production sees it. The request reaches the server, the route exists, and then the platform returns 415 Unsupported Media Type because it refuses to process the body in the format you sent. That's the right behavior when the server understands the method and URL but won't accept the request payload's media type, as documented in the HTTP standard and summarized by MDN's status 415 reference.

The fastest way to think about it is simple. The server expects one representation, the client declares another, or the bytes on the wire don't match either claim. That's why the practical fix is rarely “check headers” in the abstract, it's to compare the accepted contract, the declared Content-Type, and the actual payload bytes side by side.

Practical rule: if the body, header, and endpoint contract don't all agree, error code 415 is doing its job.

A 415 is different from a 400 or a 406. A 400 usually means the request is malformed in a broader sense, while a 406 points to response negotiation, not request-body format. If you want the broader context for similar gateway failures, this overview of a bad gateway 504 helps separate transport problems from media-type rejections.

The Three-Layer Diagnostic Workflow

Start by proving what the endpoint accepts. Check the OpenAPI spec, route docs, or gateway policy and confirm the accepted media types before touching client code. If the contract says JSON only, don't spend time tweaking XML serializers or multipart boundaries.

Next, inspect the outgoing request as raw traffic. In curl, use verbose output so you can see the headers and the body construction. In browser DevTools, inspect the network tab and compare the sent Content-Type to the actual payload. In proxy tools, look for hidden changes, especially when libraries auto-set headers. The key is to compare what the client declared with what it really emitted.

Then check server or gateway logs for the rejection point. If the request dies before application code, the parser, middleware, or edge layer is usually the culprit. That's why the fastest sequence is always, what the server expects, what the client declared, and what bytes were sent, in that order. It removes guesswork and usually exposes the exact mismatch.

If you want a process-oriented companion to this workflow, pratiques pour fiabiliser vos pipelines is worth reading alongside the request comparison step, because pipeline discipline and request parity solve the same class of drift.

For a Python-specific follow-up when the failure lives in code rather than tooling, the internal guide on catching errors in Python pairs well with this workflow.

The outage usually isn't in the business logic. It's in the parser boundary between the client and the gateway.

Common Causes Beyond Wrong Content-Type

The obvious cause is the wrong Content-Type, but production 415s often come from deeper layers. One hidden source is Content-Encoding. Apigee documents 415 failures caused by unsupported request or response encodings, and Cloudflare also notes unsupported Content-Encoding as a reason a request can be rejected before the app ever sees it. A body can be structurally valid and still fail if the declared encoding isn't one the platform accepts.

Another under-discussed trigger is file type rejection. Cloudflare's troubleshooting notes that a server can return 415 when it isn't configured to handle a file format, including certain image or document uploads. That matters for systems that ingest mixed content, where the failure isn't about JSON versus XML at all, it's about a file type the endpoint won't process.

Automation changes the pattern again. In scrapers and non-browser workflows, 415 can act like a bot-detection signal or a protocol mismatch rather than a literal media-type failure. That's why the same endpoint can succeed in Postman but fail in CI, where header fingerprints and request shape are different.

If your gateway story sounds more like access control than payload parsing, the internal note on a firewall turned off is useful because edge policy and media-type rejection often get confused during incident triage.

Fixing 415 Errors on Client and Server

On the client side, the clean fix is to make the body and header match exactly. JSON should be sent as JSON, XML as XML, form data as form data, and multipart uploads should include the correct boundary. If you're using curl, don't rely on defaults when the endpoint is strict. If you're using Postman, choose the body mode that matches the API and verify the generated headers before you copy the request into code.

Here's the practical split I use in reviews.

On the server side, make the accepted media types explicit in middleware or gateway rules, then keep that behavior consistent across environments. If a framework like Express or Django is parsing too loosely in one place and too strictly in another, you'll get the classic “works in staging, fails in prod” loop. For route-specific rejection behavior, the internal reference on forbidden 403 in Nginx helps separate permission errors from payload errors.

Server-side fix: accept only the media types you can reliably parse, then return a clear failure when clients send something else.

Wildcard acceptance sounds flexible, but it can hide integration drift. Specific media types are better when the contract matters, especially for APIs that must stay predictable across SDKs and gateways.

When Everything Looks Correct But 415 Still Appears

This is the frustrating case. The header is right, the payload is valid, and the request still comes back as 415. In automation, that often means the server is reacting to something other than the body format, such as header fingerprints, proxy behavior, or anti-blocking logic that's being surfaced through a media-type response. The Scrapfly guidance on HTTP 415 in scraping workflows is useful because it calls out those inconsistent failures directly.

The easiest sanity check is parity. If the request works in Postman but fails in CI or a scraper, diff the two requests line by line. Compare Accept, Content-Type, compression behavior, and any automatic headers added by the client runtime. If the same endpoint fails only outside a browser or API client, the problem may be a policy layer, not a serializer.

Don't ignore the possibility that 415 is a red herring. Authentication failures, rate limiting, or edge security rules can surface as media-type issues when the proxy hides the true reason. The internal walkthrough on an unexpected error has occurred is relevant here because ambiguous errors often come from the layer that intercepted the request first, not the application you intended to hit.

Preventing 415 Errors in Production Systems

Prevention starts with contracts. If your OpenAPI spec, gateway policy, and application parser all agree on accepted media types, client teams stop guessing. Add contract tests that fail when a request body, Content-Type, or Content-Encoding drifts from the documented format, and keep a small set of executable examples that mirror real traffic. That catches the failures that only show up after a gateway, proxy, or client library rewrites the request on the way to production.

Monitoring matters too. Track 415 responses at the gateway and origin, then inspect whether failures cluster around one endpoint, one client library, one deployment, or one request path that carries compressed bodies. If a release changes parser behavior, compression handling, or gateway rules, you want to see the spike before customers do. Watch for a pattern where browser calls pass but automation fails, since some WAFs and edge policies fingerprint non-browser clients and surface the rejection as a media-type error. Environment consistency pays off, because the closer staging is to production, the fewer surprises you get from strict media-type enforcement.

Document the accepted request formats in plain language, then back the docs with working examples. The goal is not to list every MIME type under the sun, it is to make the supported ones hard to misuse. Teams that keep media-type contracts visible, tested, and logged spend less time debugging and more time shipping.

If you want fewer 415 surprises in your own infrastructure, use Server Scheduler to keep dev, staging, and non-production systems aligned on the same maintenance windows and environment state. Visit Server Scheduler to standardize the conditions you debug under, so request failures are easier to reproduce and fix.