1# DDoS Gotchas
2 
3## Common Errors
4 
5### "False positives blocking legitimate traffic"
6 
7**Cause**: Sensitivity too high, wrong action, or missing exceptions  
8**Solution**:
91. Lower sensitivity for specific rule/category
102. Use `log` action first to validate (Enterprise Advanced)
113. Add exception with custom expression (e.g., allowlist IPs)
124. Query flagged requests via GraphQL Analytics API to identify patterns
13 
14### "Attacks getting through"
15 
16**Cause**: Sensitivity too low or wrong action  
17**Solution**: Increase to `default` sensitivity and use `block` action:
18```typescript
19const config = {
20  rules: [{
21    expression: "true",
22    action: "execute",
23    action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: "default", action: "block" } },
24  }],
25};
26```
27 
28### "Adaptive rules not working"
29 
30**Cause**: Insufficient traffic history (needs 7 days)  
31**Solution**: Wait for baseline to establish, check dashboard for adaptive rule status
32 
33### "Zone override ignored"
34 
35**Cause**: Account overrides conflict with zone overrides  
36**Solution**: Configure at zone level OR remove zone overrides to use account-level
37 
38### "Log action not available"
39 
40**Cause**: Not on Enterprise Advanced DDoS plan  
41**Solution**: Use `managed_challenge` with low sensitivity for testing
42 
43### "Rule limit exceeded"
44 
45**Cause**: Too many override rules (Free/Pro/Business: 1, Enterprise Advanced: 10)  
46**Solution**: Combine conditions in single expression using `and`/`or`
47 
48### "Cannot override rule"
49 
50**Cause**: Rule is read-only  
51**Solution**: Check API response for read-only indicator, use different rule
52 
53### "Cannot disable DDoS protection"
54 
55**Cause**: DDoS managed rulesets cannot be fully disabled (always-on protection)  
56**Solution**: Set `sensitivity_level: "eoff"` for minimal mitigation
57 
58### "Expression not allowed"
59 
60**Cause**: Custom expressions require Enterprise Advanced plan  
61**Solution**: Use `expression: "true"` for all traffic, or upgrade plan
62 
63### "Managed ruleset not found"
64 
65**Cause**: Zone/account doesn't have DDoS managed ruleset, or incorrect phase  
66**Solution**: Verify ruleset exists via `client.rulesets.list()`, check phase name (`ddos_l7` or `ddos_l4`)
67 
68## API Error Codes
69 
70| Error Code | Message | Cause | Solution |
71|------------|---------|-------|----------|
72| 10000 | Authentication error | Invalid/missing API token | Check token has DDoS permissions |
73| 81000 | Ruleset validation failed | Invalid rule structure | Verify `action_parameters.id` is managed ruleset ID |
74| 81020 | Expression not allowed | Custom expressions on wrong plan | Use `"true"` or upgrade to Enterprise Advanced |
75| 81021 | Rule limit exceeded | Too many override rules | Reduce rules or upgrade (Enterprise Advanced: 10) |
76| 81022 | Invalid sensitivity level | Wrong sensitivity value | Use: `default`, `medium`, `low`, `eoff` |
77| 81023 | Invalid action | Wrong action for plan | Enterprise Advanced only: `log` action |
78 
79## Limits
80 
81| Resource/Limit | Free/Pro/Business | Enterprise | Enterprise Advanced |
82|----------------|-------------------|------------|---------------------|
83| Override rules per zone | 1 | 1 | 10 |
84| Custom expressions | ✗ | ✗ | ✓ |
85| Log action | ✗ | ✗ | ✓ |
86| Adaptive DDoS | ✗ | ✓ | ✓ |
87| Traffic history required | - | 7 days | 7 days |
88 
89## Tuning Strategy
90 
911. Start with `log` action + `medium` sensitivity
922. Monitor for 24-48 hours
933. Identify false positives, add exceptions
944. Gradually increase to `default` sensitivity
955. Change action from `log` → `managed_challenge` → `block`
966. Document all adjustments
97 
98## Best Practices
99 
100- Test during low-traffic periods
101- Use zone-level for per-site tuning
102- Reference IP lists for easier management
103- Set appropriate alert thresholds (avoid noise)
104- Combine with WAF for layered defense
105- Avoid over-tuning (keep config simple)
106 
107See [patterns.md](./patterns.md) for progressive rollout examples.
108