1# Gotchas & Best Practices
2 
3## Common Errors
4 
5### 1000: "Snippet execution failed"
6Runtime error or syntax error. Wrap code in try/catch:
7```javascript
8try { return await fetch(request); }
9catch (error) { return new Response(`Error: ${error.message}`, { status: 500 }); }
10```
11 
12### 1100: "Exceeded execution limit"
13Code takes >5ms CPU. Simplify logic or move to Workers.
14 
15### 1201: "Multiple origin fetches"
16Call `fetch(request)` exactly once:
17```javascript
18// ❌ Multiple origin fetches
19const r1 = await fetch(request); const r2 = await fetch(request);
20// ✅ Single fetch, reuse response
21const response = await fetch(request);
22```
23 
24### 1202: "Subrequest limit exceeded"
25Pro: 2 subrequests, Business/Enterprise: 5. Reduce fetch calls.
26 
27### "Cannot set property on immutable object"
28Clone before modifying:
29```javascript
30const modifiedRequest = new Request(request);
31modifiedRequest.headers.set("X-Custom", "value");
32```
33 
34### "caches is not defined"
35Cache API NOT available in Snippets. Use Workers.
36 
37### "Module not found"
38Snippets don't support `import`. Use inline code or Workers.
39 
40## Best Practices
41 
42### Performance
43- Keep code <10KB (32KB limit)
44- Optimize for 5ms CPU
45- Clone only when modifying
46- Minimize subrequests
47 
48### Security
49- Validate all inputs
50- Use Web Crypto API for hashing
51- Sanitize headers before origin
52- Don't log secrets
53 
54### Debugging
55```javascript
56newResponse.headers.set("X-Debug-Country", request.cf.country);
57```
58```bash
59curl -H "X-Test: true" https://example.com -v
60```
61 
62## Available APIs
63 
64**✅ Available:** `fetch()`, `Request`, `Response`, `Headers`, `URL`, `crypto.subtle`, `crypto.randomUUID()`, `atob()`/`btoa()`, `JSON`
65 
66**❌ NOT Available:** `caches`, `KV`, `D1`, `R2`, `Durable Objects`, `WebSocket`, `HTMLRewriter`, `import`, Node.js APIs
67 
68## Limits
69 
70| Resource | Limit |
71|----------|-------|
72| Snippet size | 32KB |
73| Execution time | 5ms CPU |
74| Subrequests (Pro/Biz) | 2/5 |
75| Snippets/zone | 20 |
76 
77## Performance Benchmarks
78 
79| Operation | Time |
80|-----------|------|
81| Header set | <0.1ms |
82| URL parsing | <0.2ms |
83| fetch() | 1-3ms |
84| SHA-256 | 0.5-1ms |
85 
86**Migrate to Workers when:** >5ms needed, >5 subrequests, need storage (KV/D1/R2), need npm packages, >32KB code
87