references/waf/gotchas.md
WAF Gotchas
Use observed requests and the deployed ruleset definitions to diagnose behavior before changing protection.
| Symptom or decision | Documentation to read | |---------------------|-----------------------| | A rule executes earlier or later than expected | WAF phases and account/zone order and terminating actions | | A skip rule leaves a protection active | Skip scope, phases, products, and logging | | Updating a ruleset removes unrelated rules | Ruleset replacement semantics | | An expression fails to parse | Rules language elements | | Score-based rules match unexpected traffic | Attack score meaning, special values, and plan availability | | Managed overrides conflict | Override precedence and scope | | Legitimate traffic is blocked, or attacks reach the origin | False-positive and false-negative investigation | | Rate limits affect shared-IP users or count unexpected requests | Characteristics, NAT support, and counting expressions | | API creation fails or the request body is unclear | Custom rule creation, managed deployment, or rate limit creation |
Check account versus zone scope, rule position, and the action that actually handled the request. For rate limiting, inspect matching and counting criteria separately. Avoid broad exceptions as a shortcut for diagnosing a single false positive.
Return to api.md for operations and configuration.md for deployment ownership.