Add WAF Protection to API Gateway (2026)

API Gateway is now throwing 502 Bad Gateway errors after I added WAF protection.

The 502 Bad Gateway means your API Gateway can’t reach the upstream service, and in this case, the WAF is the intermediary that’s failing. The interesting part is that the WAF is supposed to be protecting your API, but it’s instead blocking legitimate traffic or misconfigured to reject everything.

Here are the common reasons this happens and how to fix them:

1. WAF Rule Blocking Legitimate Traffic

This is the most frequent culprit. A WAF rule, either custom or a managed rule group, is too aggressive and is flagging valid API requests as malicious.

Diagnosis: Enable WAF logging. In AWS WAF, this means configuring a logging destination (e.g., S3 bucket, CloudWatch Logs). Then, examine the WAF logs for requests that are being blocked (Action: BLOCK). Look for patterns in the blocked requests – common headers, URL paths, query parameters, or request bodies that are consistently flagged.
Fix:
- Option A (Adjust Rule): If you’re using a custom rule, refine its conditions to be less restrictive. For example, if a rule blocks requests with a specific header, add a condition to only block if the header value meets certain criteria, or if the header is missing.
- Option B (Add Exception): If you’re using a managed rule group and can’t modify it, create an explicit "Allow" rule before the managed rule group in your Web ACL. This exception rule should match the specific requests you’ve identified as legitimate in your WAF logs. For example, to allow requests to /public/data, your exception rule might look like:
```
If a request:
  matches the statement:
    Byte match condition:
      Text transformation: NONE
      Target set: URL_CODE_UNITS
      Selector: /public/data
      Overridden: false
Then:
  Override rule group action: COUNT
```
  (Note: COUNT is often safer than ALLOW initially to ensure it’s not blocking too much.)
- Option C (Disable Rule): As a last resort, if a specific managed rule is causing widespread issues and you can’t create an effective exception, you might need to disable that specific rule within the managed rule group. This is less ideal as you lose protection.
Why it works: The WAF is a rule engine. If a rule is too broad, it catches good traffic. Adjusting the rule’s conditions or adding an explicit allow rule tells the engine which specific patterns are okay, bypassing the overly strict blocking rule for those cases.

2. Incorrect IP Set Configuration

If your WAF is configured to allow traffic only from specific IP addresses or ranges, and those sets are incorrect, legitimate traffic will be blocked.

Diagnosis: Review your WAF’s IP set configurations. Ensure the CIDR blocks listed accurately reflect the IP addresses your API Gateway or the upstream services are expected to receive traffic from. Check for typos, incorrect subnet masks, or missing ranges.
Fix: Update your IP sets in the WAF Web ACL with the correct CIDR notation for your trusted IP addresses. For example, if your office has a static IP 203.0.113.45, you’d add 203.0.113.45/32 to your IP set. If your application servers are in a specific VPC subnet 10.0.1.0/24, ensure that’s included.
Why it works: The WAF checks the source IP of incoming requests against its allowed lists. Correcting these lists ensures that only traffic originating from the intended, trusted sources is permitted.

3. Rate Limiting Rules Too Strict

Aggressive rate-limiting rules can block legitimate users who make many requests in a short period, even if those requests are not malicious.

Diagnosis: Examine your WAF’s rate-based rules. Check the configured rate limits (e.g., "100 requests per 5 minutes"). Correlate these with your application’s expected traffic patterns and user behavior. Look at WAF logs to see if blocked requests are associated with specific IP addresses or API endpoints that are experiencing high legitimate traffic.
Fix: Adjust the rate limit to a more appropriate threshold. For example, if a rule blocks 100 requests per 5 minutes, you might increase it to 500 requests per 5 minutes or even 1000 requests per 1 minute depending on your application’s needs. You can also set up "exemption" rules for trusted IPs or specific endpoints that naturally have higher request volumes.
Why it works: Rate limiting is a form of traffic control. By increasing the allowed request rate, you permit higher volumes of legitimate traffic that might have previously been erroneously flagged as abusive.

4. WAF Not Associated with the Correct API Gateway Resource

This is more of a deployment oversight. The WAF Web ACL might be configured, but it’s not actually attached to the specific API Gateway stage or resource that’s experiencing the 502 errors.

Diagnosis: Navigate to your API Gateway console. Select your API and then the specific stage (e.g., prod, dev). Check the "WAF Web ACL" section for that stage. Ensure it’s populated with the correct Web ACL name.
Fix: In the API Gateway stage settings, select the correct WAF Web ACL from the dropdown list. Click "Save".
Why it works: API Gateway needs to be explicitly told which WAF to consult for incoming requests. Associating the Web ACL ensures that traffic flows through the WAF before reaching your backend services.

5. Incorrect WAF Request/Response Body Inspection Settings

If your WAF rules inspect request or response bodies, and these settings are misconfigured (e.g., wrong content type, incorrect length limits), it can cause the WAF to fail or block traffic.

Diagnosis: In your WAF Web ACL, check the "Inspected body content" settings for rules that inspect the body. Ensure the Content-Type is correctly specified (e.g., application/json, application/x-www-form-urlencoded). Also, verify that the Max request body size and Max response body size are sufficient for your API’s payloads. If you’re inspecting response bodies, ensure your backend is returning valid responses that the WAF can parse.
Fix: Adjust the "Inspected body content" settings to match your API’s actual content types and expected payload sizes. For example, if your API uses JSON, ensure application/json is listed. Increase the body size limits if your payloads are large.
Why it works: The WAF needs to know how to interpret the data it’s inspecting. Mismatched content types or excessively large bodies can lead to parsing errors within the WAF, causing it to reject the request or return an error.

6. WAF Timeout Issues

While less common for 502, the WAF itself might be timing out while processing a request before it can forward it to the backend. This can happen with very complex rules or very large payloads.

Diagnosis: Examine WAF logs for requests that take an unusually long time to process before being blocked or allowed. Also, check your API Gateway’s integration timeouts and your backend service’s response times.
Fix: Optimize your WAF rules to be more efficient. If possible, reduce the complexity or the number of rules that inspect large payloads. Ensure your backend services are responding within their configured timeouts. The default WAF timeout is typically 30 seconds. If your backend consistently takes longer, you might need to optimize the backend or re-evaluate WAF inspection points.
Why it works: If the WAF takes too long to evaluate a request, it might exceed its own internal processing limits or the upstream API Gateway’s patience, leading to a gateway error.

After fixing these, the next error you might encounter is a 403 Forbidden if your backend authorization is now being correctly enforced by the WAF.