API Gateway Mock Integration Fails with Binary Media Types "*/*" - Forces Costly Workarounds

Question

# Issue Description

API Gateway Mock integrations return 500 "Internal server error" when the API has binary media types configured as "*/*", even though the Mock integration itself is properly configured and works correctly in the Test console.

# Steps to Reproduce

- Create a REST API with Mock integration
  - Configure integration request mapping template: `{"statusCode": 200}`
  - Configure integration response for 200 status code
  - Set API binary media types to "*/*" (as recommended by AWS documentation for handling unpredictable client `Accept` headers)
  -  Test function works correctly, but actual HTTP requests return 500 errors

# Expected Behavior

Mock integrations should work regardless of binary media type configuration, since they don't involve actual binary data processing.

# Current Workarounds and Cost Impact

This limitation forces customers into more expensive alternatives:

- Lambda Integration: Adds unnecessary compute costs, cold start latency, and operational overhead for simple static responses
 - HTTP Integration: Requires maintaining external endpoints or additional AWS resources
 - API Splitting: Operational complexity of managing separate APIs

# Business Impact

- Increased costs: Mock responses should be essentially free, but now require Lambda functions
 - Architectural complexity: Forces API splitting or additional resource management
 - Performance degradation: Lambda cold starts vs. instant Mock responses

# Use Case

Many APIs need to:
 - Support binary content (images, files) via Lambda proxy integrations
 - Provide simple mock/static responses for testing, health checks, or placeholder endpoints
 - Handle unpredictable client Accept headers (requiring "*/*" binary media type)

This is a common and reasonable architecture pattern that should be supported.

re:Post Agent · Answer

Based on the AWS documentation, when you configure binary media types as "*/*" in API Gateway, the API treats all content types as binary data. This configuration affects how API Gateway handles request and response payloads across all integration types, including Mock integrations.

The "*/*" wildcard configuration is specifically recommended for scenarios where you cannot control the order of Accept header values, such as requests from browsers. API Gateway uses the first Accept header from clients to determine if a response should return binary media, and when binary media types are set to "*/*", the API interprets responses as binary payloads.

For Mock integrations specifically, the integration response can be configured with content handling strategies. When dealing with binary payloads in non-proxy integrations, you can set the integration response's contentHandling property to control how the payload is processed - for example, converting from binary to base64-encoded text using CONVERT_TO_TEXT.

The issue you're experiencing likely stems from the fact that with "*/*" configured as a binary media type, API Gateway is attempting to handle the Mock integration response as binary data, but the Mock integration is returning a text/JSON response. This mismatch in content handling expectations could cause the 500 error you're seeing.

To resolve this while maintaining support for binary content in other endpoints, you may need to configure the contentHandling property on your Mock integration response appropriately, or reconsider whether "*/*" is necessary for your specific use case. If you only need binary support for specific endpoints (like those serving images or files through Lambda proxy integrations), you might configure specific binary media types (like "image/png" or "application/octet-stream") rather than the wildcard, allowing Mock integrations to continue functioning normally for text responses.  
**Sources**  
[Binary media types for WebSocket APIs in API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/websocket-api-develop-binary-media-types.html)  
[Binary media types for REST APIs in API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings.html)

API Gateway Mock Integration Fails with Binary Media Types "/" - Forces Costly Workarounds

Issue Description

Steps to Reproduce

Expected Behavior

Current Workarounds and Cost Impact

Business Impact

Use Case

Add your answer

Relevant content