Fix 415 unsupported media type on API Gateway

Quick Answer: The "415 Unsupported Media Type" error on API Gateway indicates the client's request `Content-Type` header does not match the expected type configured for the API method or integration. First, verify the `Content-Type` header in your request payload (e.g., `application/json`) against the API Gateway method's Integration Request mapping templates. Ensure the header exactly matches the type the backend expects, such as `application/json` for JSON payloads. Correcting this header should resolve the issue.

What Causes This Error

Mismatched `Content-Type` header in client request: The `Content-Type` header sent by the client (e.g., `text/plain`) does not align with the media types API Gateway is configured to accept for the specific method.
Incorrect `Content-Type` mapping in API Gateway Integration Request: The API Gateway method's integration request is configured to expect a specific `Content-Type` (e.g., `application/xml`) but the client is sending another (e.g., `application/json`), leading to a rejection before the backend is invoked.
Backend service `Content-Type` expectation mismatch: The backend Lambda function or HTTP endpoint expects a specific `Content-Type` (e.g., `application/x-www-form-urlencoded`) that is not being correctly passed through or transformed by API Gateway, or the client is sending an incompatible type.
Missing `Content-Type` header for POST/PUT requests: For methods like POST or PUT that typically include a request body, the `Content-Type` header is entirely omitted, causing API Gateway to reject the request as it cannot determine how to process the payload.
Invalid or malformed `Content-Type` header value: The `Content-Type` header contains a syntactically incorrect value (e.g., `applicaion/json` instead of `application/json`) or an unsupported character set specification.
Binary payload misconfiguration: When sending binary data (e.g., images, files), API Gateway is not configured to handle binary media types, or the `Content-Type` header for the binary data is not explicitly listed in the API's binary media types.

Step-by-Step Fixes

Fix 1: Verify and Correct Client `Content-Type` Header

Inspect the `Content-Type` header in your client's HTTP request. For example, using `curl -v -X POST -H "Content-Type: application/json" -d '{"key":"value"}' https://your-api-gateway-url/path`.,Compare this header value with the expected content type for your API Gateway method. This is often `application/json` for JSON payloads or `application/xml` for XML.,Modify your client code or request tool to send the correct `Content-Type` header that matches what API Gateway expects. Ensure it is precisely `application/json`, `application/xml`, `text/plain`, etc., as appropriate.,Retest the API call to confirm the 415 error is resolved.

Fix 2: Configure API Gateway Method Integration Request Mapping

Navigate to your API Gateway console, select your API, then the specific method (e.g., POST /items).,Go to the 'Integration Request' section. Under 'Content-Type', check if there are any defined mapping templates.,If mapping templates exist, ensure the `Content-Type` specified (e.g., `application/json`) matches the `Content-Type` your client is sending. If not, add a new mapping template for the expected `Content-Type`.,If you are simply proxying the request to a Lambda function or HTTP endpoint, ensure 'Use Lambda Proxy integration' or 'Use HTTP Proxy integration' is enabled, as this typically bypasses explicit content-type mapping for direct passthrough.

Fix 3: Add or Update Binary Media Types in API Gateway

If you are sending binary data (e.g., images, PDF files), go to your API Gateway console, select your API, and then navigate to 'Settings' in the left navigation pane.,Under 'Binary Media Types', add the specific `Content-Type` header values for your binary data (e.g., `image/jpeg`, `application/octet-stream`, `application/pdf`). Use `*/*` to allow all binary types, but be cautious with this broad setting.,Ensure your client sends the exact `Content-Type` header that matches one of the configured binary media types.,For Lambda proxy integrations, ensure your Lambda function correctly decodes the base64-encoded body if `isBase64Encoded` is true in the event object.

Fix 4: Inspect Backend Service `Content-Type` Expectations

If API Gateway is passing the request through but the backend (e.g., Lambda, EC2 instance) is rejecting it, the issue might be the backend's expectation.,Review the documentation or code for your backend service to understand what `Content-Type` it expects for the specific endpoint.,Adjust API Gateway's integration request mapping templates to transform the client's `Content-Type` into what the backend expects, or modify the client to send the type the backend natively supports.,For example, if the backend expects `application/x-www-form-urlencoded` but the client sends `application/json`, you might need a mapping template to transform the JSON body into form data.

Fix 5: Check for Malformed `Content-Type` Header

Carefully examine the `Content-Type` header value being sent by the client for any typos, extra spaces, or invalid characters.,Ensure the header follows standard HTTP specifications, for example, `Content-Type: application/json; charset=utf-8` is valid, but `Content-Type: application/json;charset=utf-8` (no space after semicolon) might be interpreted differently by some parsers.,Use a network inspection tool (e.g., browser developer tools, Wireshark, Postman's console) to see the raw HTTP request headers being sent.,Correct any syntax errors in the `Content-Type` header value in your client application.

Advanced Fixes

Advanced Fix 1: Custom Authorizer for `Content-Type` Validation

Implement a Lambda Authorizer (formerly Custom Authorizer) that inspects the `Content-Type` header of incoming requests.,Within the Lambda Authorizer function, retrieve the `event.headers['Content-Type']`.,If the `Content-Type` is not among the expected types for the invoked method, return an 'Unauthorized' (401) or 'Forbidden' (403) response with a custom message indicating the unsupported media type, preventing the request from reaching the integration.,Configure your API Gateway methods to use this Lambda Authorizer.

Advanced Fix 2: WAF Rule for `Content-Type` Filtering

Create an AWS WAF Web ACL and associate it with your API Gateway stage.,Add a rule that inspects the 'Header' field, specifically the 'Content-Type' header.,Configure a string match condition to block requests where the `Content-Type` header does not match a predefined whitelist of acceptable media types, or contains specific blacklisted types.,Set the rule action to 'Block' to prevent requests with unsupported media types from reaching API Gateway's core processing logic, providing an earlier rejection point.

FAQs

Q: What is `Content-Type` and why is it important for API Gateway?

A: The `Content-Type` header informs the server about the format of the data being sent in the request body (e.g., `application/json`, `text/xml`, `image/jpeg`). API Gateway uses this header to determine how to parse the request body, apply mapping templates, and pass the data to the backend. If the `Content-Type` doesn't match what API Gateway or the backend expects, it results in a 415 error.

Q: Does API Gateway automatically handle `Content-Type` transformations?

A: No, API Gateway does not automatically transform `Content-Type` headers or payload formats. You must explicitly configure mapping templates in the 'Integration Request' section to transform the request body from one format (e.g., JSON) to another (e.g., XML) or to a different `Content-Type` for the backend. For proxy integrations, the `Content-Type` is typically passed directly.

Q: I'm sending binary data, but still getting 415. What am I missing?

A: For binary data, you must explicitly list the expected binary media types (e.g., `image/png`, `application/octet-stream`) in your API's 'Settings' within the API Gateway console. Additionally, ensure your client sends the correct `Content-Type` header matching one of these configured types. If using Lambda proxy integration, the binary body will be base64-encoded, and your Lambda function must decode it.

Q: How can I debug the `Content-Type` header being sent by my client?

A: You can use various tools: 1. **Browser Developer Tools**: For web applications, open the Network tab. 2. **Postman/Insomnia**: Check the 'Headers' tab in the request builder and the 'Console' for raw request details. 3. **`curl -v`**: Add the `-v` flag to `curl` commands to see verbose output, including request headers. 4. **AWS CloudWatch Logs**: Enable CloudWatch logging for your API Gateway stage to capture detailed request and response information, including headers.

Q: What's the difference between 415 and 400 errors regarding content types?

A: A **415 Unsupported Media Type** error specifically means the server (API Gateway in this case) understands the request's `Content-Type` header but finds it unacceptable or unsupported for the resource. A **400 Bad Request** error is more general, indicating the server cannot process the request due to a client error, which could include a malformed request body, missing required parameters, or other protocol violations, but not necessarily an unsupported media type.