How to Fix: AWS API Gateway 502 Bad Gateway

The Scenario

You’re rolling out a new Lambda integration behind API Gateway on a Thursday afternoon. After the deploy, your mobile app team starts pinging you — every other request to POST /api/v2/orders returns a 502. The canary deployment passed, but production is melting down.

Symptoms

curl returns: {"message": "Internal server error"} with HTTP 502
CloudWatch logs for API Gateway show Execution failed due to integration error
No corresponding error logs in your Lambda or HTTP backend — the request never reaches it

Root Cause

API Gateway returns a 502 when the integration endpoint (Lambda, HTTP, or VPC Link) either times out, returns a malformed response, or is unreachable. The default integration timeout is 29 seconds. The most common cause is the backend taking longer than that, or a VPC connectivity issue where the Lambda can’t reach a private resource (RDS, Elasticache) within the timeout window. Less common but brutal: the backend returns a response body larger than 10MB (the API Gateway payload limit), or returns non-JSON content when the integration expects it.

Resolution (Step-by-Step)

Check the integration timeout — bump it to 29 seconds max (it’s already there by default, but verify):
```
aws apigateway get-integration --rest-api-id <api-id> --resource-id <resource-id> --http-method POST
```
Look for "timeoutInMillis": 29000. If your backend needs more than 29s, you need to refactor (or use an async pattern with a 202 response).
Check Lambda timeout vs API Gateway timeout — Lambda’s timeout must be less than API Gateway’s 29s:
```
aws lambda get-function-configuration --function-name <function-name> --query 'Timeout'
```
If it’s 30 or more, reduce it to 28. Lambda will return a 200 to API Gateway before it actually finishes — that’s a silent data loss.
For VPC-backed Lambdas, test connectivity — the 502 often hides a VPC timeout. Run this from the Lambda’s VPC:
```
aws ec2 describe-network-interfaces --filters Name=group-id,Values=<security-group-id>
```
Check the Lambda’s ENI is attached and the security group allows outbound to your target (RDS/ElastiCache). Add a VPC endpoint for services like SQS or S3 if needed.
Check response size — if your backend returns >10MB, API Gateway will hang up. Add logging on the backend to measure payload size. If it’s close, compress or paginate.
Validate the integration response mapping — a missing or malformed mapping template causes 502:
```
aws apigateway get-integration-response --rest-api-id <api-id> --resource-id <resource-id> --http-method POST --status-code 200
```
Ensure "responseTemplates" has a valid mapping (or is empty for passthrough). A bad regex in the template will silently fail.

Why This Sometimes Doesn’t Work

You check all the above and it’s still 502. The culprit might be a WAF rule silently blocking the response. API Gateway integrated with AWS WAF can drop responses that match certain conditions (e.g., response header size, body content). WAF logs won’t show this as a “block” — it looks like a silent drop. Check WAF ACLs attached to the API stage and look for Count vs Block actions on response inspection rules. Also, if you’re using a custom domain with an ACM certificate, a mismatched or expired certificate will cause a 502 on the TLS handshake — CloudFront’s error logs are the place to look, not API Gateway’s.

Verification

After applying the fix, hit the endpoint with a verbose curl to confirm HTTP 200 and the right response body:

curl -v -X POST https://<api-id>.execute-api.<region>.amazonaws.com/prod/api/v2/orders -H "Content-Type: application/json" -d '{"test": true}'

Then check API Gateway CloudWatch logs for Successfully completed execution — no more integration errors.

Common Follow-up Questions

Q: Why does the 502 happen intermittently? A: Likely a Lambda cold start exceeding the 29s timeout, or a VPC connectivity issue that only triggers under load (e.g., ENI scaling limits). Provisioned concurrency fixes the cold start; NAT Gateway bandwidth fixes the VPC issue.

Q: Can I increase the API Gateway timeout beyond 29 seconds? A: No, 29s is the hard limit. If your backend needs more, switch to an async pattern: API Gateway returns 202 immediately, and the client polls another endpoint for the result.

Q: The Lambda runs fine when tested manually but fails through API Gateway. A: Check the Lambda’s resource policy — API Gateway needs lambda:InvokeFunction permission. Also ensure the Lambda is in the same region as the API Gateway.

Prevent This in the Future

API Gateway 502s are almost always a symptom of a backend that’s misconfigured or overloaded. Set up proactive monitoring on your integration latency and error rate — catch the 4xx/5xx spike before your users do. Better Stack’s uptime monitoring and incident management tools can alert you the moment your API Gateway error rate crosses a threshold, and correlate it with backend metrics in one place.

Set up uptime monitoring and alerts with Better Stack