update skills

.agents/skills/cloudflare-deploy/references/api-shield/gotchas.md

@@ -0,0 +1,125 @@
+# Gotchas & Troubleshooting
+
+## Common Errors
+
+### "Schema Validation 2.0 not working after migration"
+
+**Cause:** Classic rules still active, conflicting with new system
+**Solution:**
+1. Delete ALL Classic schema validation rules
+2. Clear Cloudflare cache (wait 5 min)
+3. Re-upload schema via new Schema Validation 2.0 interface
+4. Verify in Security > Events
+5. Check action is set (Log/Block)
+
+### "Schema validation blocking valid requests"
+
+**Cause:** Schema too restrictive, missing fields, or incorrect types
+**Solution:** 
+1. Check Firewall Events for violation details
+2. Review schema in Settings
+3. Test schema in Swagger Editor
+4. Use Log mode to validate before blocking
+5. Update schema with correct specifications
+6. Ensure Schema Validation 2.0 (not Classic)
+
+### "JWT validation failing"
+
+**Cause:** JWKS mismatch with IdP, expired token, wrong header/cookie name, or clock skew
+**Solution:** 
+1. Verify JWKS matches IdP configuration
+2. Check token `exp` claim is valid
+3. Confirm header/cookie name matches config
+4. Test token at jwt.io
+5. Account for clock skew (±5 min tolerance)
+6. Use modern syntax: `is_jwt_valid(http.request.jwt.payload["{config_id}"][0])`
+
+### "BOLA detection false positives"
+
+**Cause:** Legitimate sequential access patterns, bulk operations, or sensitivity too high
+**Solution:**
+1. Review BOLA events in Security > Events
+2. Lower sensitivity threshold (High → Medium → Low)
+3. Exclude legitimate bulk operations from detection
+4. Ensure session identifiers uniquely identify users
+5. Verify minimum traffic requirements met (1000+ req/day)
+
+### "Risk labels not appearing in firewall rules"
+
+**Cause:** Feature not enabled, insufficient traffic, or missing session identifiers
+**Solution:**
+1. Verify Schema Validation 2.0 enabled
+2. Enable BOLA Detection in schema settings
+3. Configure session identifiers (required for BOLA)
+4. Wait 24-48h for ML model training
+5. Check minimum traffic thresholds met
+
+### "Endpoint discovery not finding APIs"
+
+**Cause:** Insufficient traffic (<500 reqs/10d), non-2xx responses, Worker direct requests, or incorrect session ID config
+**Solution:** Ensure 500+ requests in 10 days, 2xx responses from edge (not Workers direct), configure session IDs correctly. ML updates daily.
+
+### "Sequence detection false positives"
+
+**Cause:** Lookback window issues, non-unique session IDs, or model sensitivity
+**Solution:** 
+1. Review lookback settings (10 reqs to managed endpoints, 10min window)
+2. Ensure session ID uniqueness per user (not shared tokens)
+3. Adjust positive/negative model balance
+4. Exclude legitimate workflows from detection
+
+### "GraphQL protection blocking valid queries"
+
+**Cause:** Query depth/size limits too restrictive, complex but legitimate queries
+**Solution:**
+1. Review blocked query patterns in Security > Events
+2. Increase max_depth (default: 10) if needed
+3. Increase max_size (default: 100KB) for complex queries
+4. Whitelist specific query signatures
+5. Use Log mode to tune before blocking
+
+### "Token invalid"
+
+**Cause:** Configuration error, JWKS mismatch, or expired token
+**Solution:** Verify config matches IdP, update JWKS, check token expiration
+
+### "Schema violation"
+
+**Cause:** Missing required fields, wrong data types, or spec mismatch
+**Solution:** Review schema against actual requests, ensure all required fields present, validate types match spec
+
+### "Fallthrough"
+
+**Cause:** Unknown endpoint or pattern mismatch
+**Solution:** Update schema with all endpoints, check path pattern matching
+
+### "mTLS failed"
+
+**Cause:** Certificate untrusted/expired or wrong CA
+**Solution:** Verify cert chain, check expiration, confirm correct CA uploaded
+
+## Limits (2026)
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| OpenAPI version | v3.0.x only | No external refs, must be valid |
+| Schema operations | 10K (Enterprise) | Contact for higher limits |
+| JWT validation sources | Headers/cookies only | No query params/body |
+| Endpoint discovery | 500+ reqs/10d | Minimum for ML model |
+| Path normalization | Automatic | `/profile/238` → `/profile/{var1}` |
+| Schema parameters | No `content` field | No object param validation |
+| BOLA detection | 1000+ reqs/day/endpoint | Per-endpoint minimum |
+| Session ID uniqueness | Required | BOLA/Sequence need unique IDs |
+| GraphQL max depth | 1-50 | Default: 10 |
+| GraphQL max size | 1KB-1MB | Default: 100KB |
+| JWT claim nesting | 10 levels max | Use dot notation |
+| mTLS CA certificates | 5 custom max | CF-managed unlimited |
+| Schema upload size | 5MB max | Compressed OpenAPI spec |
+| Volumetric abuse baseline | 7 days training | Initial ML period |
+| Auth Posture refresh | Daily | Updated nightly |
+
+## See Also
+
+- [configuration.md](configuration.md) - Setup guides to avoid common issues
+- [patterns.md](patterns.md) - Best practices and progressive rollout
+- [API Shield Docs](https://developers.cloudflare.com/api-shield/)