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

The WAF only allows GET, POST, and HEAD by default. If your API uses PUT, DELETE, PATCH, or OPTIONS, those methods need to be explicitly enabled in your WAF dashboard under HTTP Verb Filtering.

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.

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 — Enable the required HTTP method. Go to your WAF dashboard and allow the method (PUT, DELETE, PATCH, or OPTIONS) under HTTP Verb Filtering.

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.

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 paths from the start. If you know an endpoint receives automated traffic (webhooks, health checks, API-to-API calls), allowlist it proactively.
  • 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: