415 Unsupported Media Type

Client Error

The server refuses to process the request because the payload's media type is not supported. The 415 response should include an Accept-Patch or Accept-Post header (depending on the method) listing the media types the endpoint does accept. This is the right answer when a JSON API receives form-encoded data or when an image upload endpoint receives an unsupported file format, not when the data is well-formed but semantically wrong.

When does this happen?

Return 415 when the Content-Type or Content-Encoding of the request body is one your handler cannot process. Common cases include sending application/x-www-form-urlencoded data to an endpoint that only parses JSON, sending an unsupported image format to an upload endpoint, or sending gzip-encoded payload to a server that does not decompress. Some APIs also return 415 for Accept-header mismatches on responses, although that is more conventionally 406. Browsers do not surface 415 specifically. Clients see a failure and must interpret the status. APIs should include an Accept-Post or Accept-Patch header in the response listing supported media types so clients can self-correct without guessing.

Common causes

• Missing Content-Type header on a POST or PUT. The server cannot tell how to parse the body.
• Wrong Content-Type. E.g. sending application/x-www-form-urlencoded to a JSON-only endpoint.
• Unsupported file format. Uploading a HEIC image to an endpoint that only accepts JPEG and PNG.
• Content-Encoding the server does not handle. E.g. sending Content-Encoding: br when the server only supports gzip.
• Body is the right format but Content-Type is mistyped (e.g. application/jason instead of application/json).
• Charset suffix the server does not accept. E.g. application/json; charset=utf-16 when the server expects utf-8.
• Multipart upload missing the boundary parameter. The server cannot parse the body without it.

How to fix it

• Set Content-Type correctly for the request body. Application/json for JSON, multipart/form-data for file uploads, etc.
• Inspect the Accept-Post or Accept-Patch header in the 415 response. It lists the supported media types.
• Convert the file or payload to a supported format before sending. HEIC to JPEG, BMP to PNG, etc.
• Confirm Content-Encoding matches what the server supports. When in doubt, omit it and let the server treat the body as identity-encoded.
• When using multipart, ensure the boundary is included in Content-Type and not duplicated in the body.
• Read the API documentation for the endpoint and the exact Content-Type expected. Many APIs are strict and reject close-but-wrong values.

Real-world examples

Client POSTs JSON to /v1/users without a Content-Type header.

Server returns 415 because it cannot determine the body format. Client adds Content-Type: application/json and the request succeeds.

Mobile app uploads a HEIC photo to an endpoint that only accepts JPEG and PNG.

Server returns 415 with Accept-Post: image/jpeg, image/png. App transcodes the photo to JPEG before retrying.

Old SDK sends form-encoded credentials to a JSON-only login endpoint.

Server returns 415. The SDK is patched to send application/json with the same fields.

Client sends Content-Encoding: br on a body the server does not know how to decompress.

Server returns 415. Client drops the encoding header and resends the body as identity-encoded.

Multipart upload missing the boundary parameter in Content-Type.

Server returns 415 because it cannot parse the body. Client regenerates the request with a proper multipart/form-data; boundary=... header.

How it differs from related codes

HTTP 400

400 means the body could not be parsed at all (malformed JSON, broken framing). 415 means the body is well-formed but the type is unsupported.

HTTP 422

422 means the data is well-formed and the type is supported, but the values fail business validation. 415 is upstream of 422. You cannot fail validation if the type is wrong.

HTTP 406

406 is the inverse: the server cannot produce a response in the media type the client asked for (Accept header mismatch). 415 is about the request body's Content-Type, not the response.

Related status codes

400 405 422 500