HTTP 415 Unsupported Media Type explained

The symptom

An API call or file upload returns 415 Unsupported Media Type. The request is well-formed and reaches the server, but the server refuses the payload because the media type does not match what the endpoint accepts. In most browsers the network tab shows a 415 on the failing request with the request body abandoned.

What 415 means

415 Unsupported Media Type signals a mismatch between the media type of the request payload and what the server expects or accepts. The server checks the Content-Type header against a whitelist for the resource, and rejects when the type is unsupported. It is different from 400 Bad Request (malformed syntax) and 411 Length Required (missing Content-Length).

Common causes

• Wrong Content-Type. Sending text/plain when the endpoint expects application/json, or application/json when it expects a multipart form.
• A mismatch between the declared type and the actual body. The server trusts the header, so declaring application/json while sending plain text or a non-JSON body often triggers a parse-related 415 on stricter servers.
• Range uploads miss the multipart framing. Services expecting Content-Range or multipart chunk framing reject a plain body with 415 when the framing type is absent.
• An unsupported compression or content coding on the payload.

Fix the request

1. Open the network tab and check the failing request's Content-Type header and body preview.
2. Compare it with the endpoint contract. If the API expects JSON, set Content-Type: application/json and send a valid JSON body:

POST /api/items HTTP/1.1
Content-Type: application/json

{"name": "Widget", "sku": "W-100"}

1. For file uploads, use the correct multipart framing, e.g. Content-Type: multipart/form-data; boundary=....
2. Send a minimal request (curl, the REST client) with an explicit header to isolate whether the code or the framework is adding the wrong type.

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"Widget"}' https://api.example.com/api/items

1. If the API is fine in the docs but rejects your SDK call, your HTTP client may be defaulting to a URL-encoded form where no Content-Type was set; set it explicitly.

Fix the server side

When you own the API, a 415 should be accompanied by a Content-Type or a response body that states the accepted types, and it must be returned only for genuinely unsupported media, never for a correctly-typed request. Validate the Content-Type early in the middleware, and return a clear "expected x, received y" message so clients can correct themselves, mirroring the diagnostic style of the 400 Bad Request guide. If clients upload in ranges, document the exact headers and framing required. Keep the acceptable media types small and explicit so 415 stays a precise contract signal rather than a mystery.