Fix guides

Vercel 403 with x-vercel-mitigated or a Security Checkpoint page blocking your API, webhook, or form

Your Vercel app works in the browser, but API clients, webhooks, cron jobs, or a form get 403 or 429 with x-vercel-mitigated: challenge or deny. How to find which firewall rule fired and let legitimate traffic through without switching protection off.

Free · no card

Paste your error. Get a free diagnosis by email.

Tell us what broke and we’ll email you a short diagnosis: the likely cause and what to try first. Usually within a day.

No passwords or secret keys, please. We only use your email to reply about this.

What you are seeing

Why it happens

  1. The Bot Protection managed ruleset is set to Challenge. It serves a JavaScript challenge to traffic that does not behave like a browser. Per Vercel's docs, API routes behind a challenge only work inside a browser session that already passed it, and scripts cannot establish one.
  2. Attack Mode is on. Every visitor must pass a challenge except known bots, and Vercel's docs warn that standalone APIs and unrecognized automated services may be blocked. It stays on for the 1, 6, or 24 hours you picked.
  3. A custom rule challenges or denies more than intended, such as a rule on /api/* or a "challenge cURL requests" template. Rules can also live in vercel.json under routes with a mitigate action. On Pro and Enterprise, a persistent action keeps blocking that IP for a set time even after the request changes.
  4. Vercel's own platform-level mitigations (DDoS protection and managed detections) fired. A Bypass custom rule does not override these; Vercel's docs point to System Bypass Rules (Pro and Enterprise) for specific IPs.
  5. Protection Bypass for Automation skips Deployment Protection, bot protection, and system mitigations for requests carrying the secret, but per Vercel's docs not active DDoS mitigations or challenges triggered by attack patterns.
  6. A reverse proxy such as Cloudflare (orange cloud) sits in front of Vercel. Vercel's docs say Bot Protection does not work behind one and real users may be challenged repeatedly.

How to fix it

1. Confirm it is the firewall, and capture the request id

curl -sS -D - -o /dev/null https://yourapp.com/api/your-route

# x-vercel-mitigated: challenge  -> a challenge rule or Attack Mode
# x-vercel-mitigated: deny       -> a deny rule or a platform mitigation
# copy the x-vercel-id value; support needs it

2. Find which rule fired

In the Vercel dashboard, open the project, then Firewall. In the overview and Traffic views, narrow to the time and path of the blocked request and note the action and the rule or detection name. Bot Protection, Attack Mode, a custom rule you can edit, and a platform mitigation each have a different fix below.

3. If Attack Mode is on, turn it off once the attack is over

On the Firewall page, open the menu at the top right and choose Disable Attack Mode. It is meant for active attacks, not as a permanent setting, and it turns itself off when the period you chose ends.

4. Let trusted traffic skip Bot Protection and your rules with a Bypass rule

Firewall > Configure > Add New > Rule

Name:   Allow server-to-server API clients
If:     Request Path   starts with   /api/public/
AND:    Request Header x-client-key  equals  <a long random value you give each client>
Then:   Bypass

Drag it above any Challenge or Deny rule, then Review Changes > Publish.
Still check the key in your route code: the firewall is not your auth.

5. Webhooks: exclude the webhook path from your own rules

Stripe's and GitHub's webhook senders are on Vercel's verified bots list, which Bot Protection and Attack Mode let through, but a custom Challenge or Deny rule covering your whole API path still catches them. Add a Bypass rule for the exact webhook path (for example /api/webhooks/stripe) above that rule, and keep verifying the signature in the handler.

6. Check for rules shipped in vercel.json

grep -n '"mitigate"' vercel.json

# vercel.json rules only support challenge and deny.
# Narrow the src pattern or remove the rule, then redeploy.

7. Your own automation: send the bypass secret as a header

curl -H "x-vercel-protection-bypass: $VERCEL_AUTOMATION_BYPASS_SECRET" \
  https://yourapp.com/api/health

# create the secret under Settings > Deployment Protection.
# It also bypasses Deployment Protection, so use it only in your own
# CI, monitors, and tests, never in a public app or a client's hands.

8. Behind Cloudflare: pick one bot layer

Either set the Cloudflare records that point at Vercel to DNS only (grey cloud), or keep the Cloudflare proxy and leave Vercel's Bot Protection off. Running both is what causes repeated challenges for real visitors.

9. Platform-level blocks you cannot edit

If the deny names no rule of yours (for example a managed detection) and the traffic is legitimate: on Pro or Enterprise, add a System Bypass Rule for the caller's fixed IP or CIDR. On Hobby, or for a false positive on a public form, post in the Vercel Community or open a support case with the request ID from step 1, the timestamp, the path, and the rule name from the Traffic view.

How to know it is fixed

The same curl from step 1 returns your API's normal status with no x-vercel-mitigated header, webhook deliveries in Stripe or GitHub show 2xx, and the Firewall Traffic view lists the request under your Bypass rule. Browse the site normally in a private window to confirm real visitors are not challenged. Sources: Vercel: Firewall concepts (challenge limitations, bypass), Vercel: Bot management and verified bots, Vercel: Attack Mode, Vercel: WAF custom rules, Vercel: rule actions, Vercel: System Bypass Rules, and Vercel: Protection Bypass for Automation. Related: Stripe webhook fails with a redirect.