Docs

Troubleshooting 403 WAF Blocks

Overview

A 403 response from the WAF means the request reached the WAF edge network and was rejected because it matched a security rule. The WAF inspected the request, determined it was potentially malicious or violated a configured rule, and blocked it before it reached your Heroku application.

Client → WAF Edge ✕ (blocked by rule) → Your Heroku App (never sees the request)

This is different from a 502 error (where the WAF allowed the request but your app didn’t respond) and from a connection timeout (where the request never reached the WAF at all). See Understanding HTTP Responses and Network Timeouts for how to tell these apart.

Is It a WAF Block or an Application 403?

Not every 403 comes from the WAF. Your application can also return a 403 for its own reasons (authentication failures, permission checks, etc.).

WAF block: - Shows a WAF block page with an incident ID and a block reason - The blocked request appears in your WAF logs - The block page looks different from your application’s normal error pages

Application 403: - Shows your application’s own error page or JSON error response - Does not appear in WAF logs as a block - The WAF allowed the request through — your app rejected it

If you see your application’s own error page, the WAF is not the issue. Debug it in your application code.

Common Block Reasons

When the WAF blocks a request, the block page and WAF logs will show the reason. Common reasons include:

Intrusion Detection — The request contained patterns that match known attacks (SQL injection, XSS, remote code execution, etc.). These rules are always active and protect against common web vulnerabilities.

Blocked IP — The requesting IP address is on your blocklist. Check your IP blocking rules.

Country Block — The request originated from a country you have blocked. Check your country blocking settings.

User Agent Block — The request’s user agent matched a blocked pattern. Check your user agent blocking rules.

HTTP Method Block — The request used an HTTP method (PUT, DELETE, PATCH, OPTIONS) that is not enabled. Check your HTTP method settings.

Path Block — The request URL matched a blocked path pattern. Check your path blocking rules.

See the Block Codes Reference for a full list of block reasons and what they mean.

Resolving False Positives

If the WAF is blocking legitimate traffic, you have two options:

IP Allowlisting

Add the IP address to your allowlist. Allowlisted IPs bypass all WAF security checks. This is best for:

  • Your team’s office IPs
  • Monitoring services (Pingdom, UptimeRobot, etc.)
  • Known API clients and integration partners
  • CI/CD pipeline IPs

Path Allowlisting

Exempt specific URL paths from WAF security checks. Requests to allowlisted paths bypass all WAF rules. This is best for:

  • Webhook endpoints (Stripe, GitHub, etc.)
  • Health check endpoints
  • API endpoints used by automated systems that send requests the WAF may flag

See Allowlisting URL Paths for setup instructions.

Debugging a WAF Block

  1. Check WAF logs — Find the blocked request. The log entry will show the IP address, URL path, block reason, and timestamp.

  2. Identify the block reason — Look up the block code in the Block Codes Reference to understand what rule was triggered.

  3. Determine if the block is correct — Was this actually malicious traffic? If yes, the WAF is working as intended. If no, proceed to create an exception.

  4. Create an exception — Add the IP to your allowlist or allowlist the URL path, depending on whether the issue is specific to one source or one endpoint.

  5. Test — After creating the exception, retry the request to confirm it now passes through.

Not Seeing a 403?

If you are experiencing access issues but not seeing a 403 error or a WAF block page, the problem may not be a WAF block at all:

Need Help?

If you need help understanding why traffic is being blocked or configuring exceptions: