Docs

Troubleshooting API Blocks

Overview

API endpoints sometimes get blocked by the WAF because automated requests can look similar to attack traffic. If your API clients, webhooks, or integrations are receiving 403 responses from the WAF, this guide will help you diagnose and resolve the issue.

Symptoms

  • API clients receive 403 Forbidden instead of the expected response
  • Webhook deliveries from third-party services (Stripe, GitHub, Slack, etc.) are failing
  • Automated scripts or CI/CD pipelines cannot reach your application
  • The 403 response includes a WAF block page with an incident ID

If the 403 shows your application’s own error page (not a WAF block page), the block is coming from your application, not the WAF. See Troubleshooting 403 WAF Blocks for how to tell the difference.

Common Causes

1. Request Body Triggers Intrusion Detection

API requests often contain JSON, XML, or encoded data that can match intrusion detection patterns. For example:

  • JSON payloads with SQL-like syntax (SELECT, DROP, UNION)
  • HTML content in form submissions (flagged as XSS)
  • Base64-encoded data that decodes to suspicious patterns
  • URL-encoded data with path traversal sequences

2. Request Size Exceeds Upload Limit

Large API payloads (file uploads, bulk data imports) may exceed your configured maximum request size. The default is relatively low for standard web forms.

3. Blocked HTTP Method

New WAFs allow PUT, PATCH, DELETE, and OPTIONS by default, and GET, POST, and HEAD are always permitted. A method block usually means the method was disabled after setup, or your client used an uncommon verb like TRACE or CONNECT. Methods are managed under Traffic Rules > HTTP Methods in your WAF dashboard.

4. Rate Limiting

High-frequency API calls from a single IP can trigger rate limiting, resulting in 429 Too Many Requests responses.

5. IP or Country Block

The API client’s IP address may be on your blocklist, or the client may be connecting from a country you have blocked.

6. Burst-Triggered Temporary IP Bans

A rapid burst of requests from a single IP can trigger intrusion detection even when the traffic is legitimate, such as a payment provider delivering a batch of notifications or a service retrying failed webhooks. When this happens, the WAF may temporarily ban the source IP at the network edge. During the ban:

  • The first few requests receive 403 responses and appear in your block logs
  • Later connections are dropped without any HTTP response
  • Dropped connections are not recorded in your block logs

To the sending service, your server appears unreachable for roughly 20 to 35 minutes, with only a handful of block log entries marking the start. Senders that retry on a schedule can trigger the ban again, producing repeated outage windows. If you receive webhooks, see Receiving Webhooks Through the WAF for how to prevent this.

How to Fix It

Step 1: Check WAF Logs

Go to your Block Logs page in the WAF dashboard. Find the blocked request and note the block reason code. This tells you exactly which rule triggered the block. See the Block Codes Reference for what each code means.

Step 2: Apply the Right Exception

Based on the block reason:

For intrusion detection blocks: Allowlist the API path. Navigate to Path Rules > Allow and add the API endpoint path (e.g., /api/webhooks/stripe). This exempts all requests to that path from WAF security checks. See Allowlisting URL Paths.

For upload size blocks: Increase your upload limit. Go to Traffic Rules > Upload Size and select a higher limit. See Maximum Request Size.

For HTTP method blocks: Re-enable the required HTTP method under Traffic Rules > HTTP Methods in your WAF dashboard.

For rate limiting: Allowlist the API client’s IP address so it bypasses rate limits. Or allowlist the API path to exempt it from all WAF checks.

For IP/country blocks: Add the API client’s IP to your allowlist, or verify your country blocking settings.

For temporary IP bans: Add the sending service’s IP address to your allowlist under Traffic Rules > Allow IPs. Senders with fixed, published IP addresses (payment gateways in particular) should be allowlisted proactively. Prefer allowlisting the IP over the path: the path stays protected against every other source.

Step 3: Test

After applying the exception, retry the API request to confirm it passes through.

Best Practices for API Endpoints Behind the WAF

  • Allowlist webhook senders from the start. If you know an endpoint receives automated traffic (webhooks, health checks, API-to-API calls), allowlist the sender’s IP when it is fixed, or the path when sender IPs rotate. See Receiving Webhooks Through the WAF.
  • Use the most specific match pattern when allowlisting. An Equals match on /api/webhooks/stripe is safer than a Begins With match on /api.
  • Enable only the HTTP methods you need. Do not enable all methods if your API only uses POST.
  • Set the upload limit to match your application’s needs, not higher.

Need Help?

If you cannot determine why an API request is being blocked or need help configuring exceptions: