1# Gotchas & Troubleshooting
2 
3## Rate Limits & 429 Errors
4 
5**Actual Limits:**
6- **1200 requests / 5 minutes** per user/token (global)
7- **200 requests / second** per IP address
8- **GraphQL: 320 / 5 minutes** (cost-based)
9 
10**SDK Behavior:**
11- Auto-retry with exponential backoff (default 2 retries, Go: 10)
12- Respects `Retry-After` header
13- Throws `RateLimitError` after exhausting retries
14 
15**Solution:**
16 
17```typescript
18// Increase retries for rate-limit-heavy workflows
19const client = new Cloudflare({ maxRetries: 5 });
20 
21// Add application-level throttling
22import pLimit from 'p-limit';
23const limit = pLimit(10); // Max 10 concurrent requests
24```
25 
26## SDK-Specific Issues
27 
28### Go: Required Field Wrapper
29 
30**Problem:** Go SDK requires `cloudflare.F()` wrapper for optional fields.
31 
32```go
33// ❌ WRONG - Won't compile or send field
34client.Zones.New(ctx, cloudflare.ZoneNewParams{
35    Name: "example.com",
36})
37 
38// ✅ CORRECT
39client.Zones.New(ctx, cloudflare.ZoneNewParams{
40    Name: cloudflare.F("example.com"),
41    Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{
42        ID: cloudflare.F("account-id"),
43    }),
44})
45```
46 
47**Why:** Distinguishes between zero value, null, and omitted fields.
48 
49### Python: Async vs Sync Clients
50 
51**Problem:** Using sync client in async context or vice versa.
52 
53```python
54# ❌ WRONG - Can't await sync client
55from cloudflare import Cloudflare
56client = Cloudflare()
57await client.zones.list()  # TypeError
58 
59# ✅ CORRECT - Use AsyncCloudflare
60from cloudflare import AsyncCloudflare
61client = AsyncCloudflare()
62await client.zones.list()
63```
64 
65## Token Permission Errors (403)
66 
67**Problem:** API returns 403 Forbidden despite valid token.
68 
69**Cause:** Token lacks required permissions (scope).
70 
71**Scopes Required:**
72 
73| Operation | Required Scope |
74|-----------|----------------|
75| List zones | Zone:Read (zone-level or account-level) |
76| Create zone | Zone:Edit (account-level) |
77| Edit DNS | DNS:Edit (zone-level) |
78| Deploy Worker | Workers Script:Edit (account-level) |
79| Read KV | Workers KV Storage:Read |
80| Write KV | Workers KV Storage:Edit |
81 
82**Solution:** Re-create token with correct permissions in Dashboard → My Profile → API Tokens.
83 
84## Pagination Truncation
85 
86**Problem:** Only getting first 20 results (default page size).
87 
88**Solution:** Use auto-pagination iterators.
89 
90```typescript
91// ❌ WRONG - Only first page (20 items)
92const page = await client.zones.list();
93 
94// ✅ CORRECT - All results
95const zones = [];
96for await (const zone of client.zones.list()) {
97  zones.push(zone);
98}
99```
100 
101## Workers Subrequests
102 
103**Problem:** Rate limit hit faster than expected in Workers.
104 
105**Cause:** Workers subrequests count as separate API calls.
106 
107**Solution:** Use bindings instead of REST API in Workers (see ../bindings/).
108 
109```typescript
110// ❌ WRONG - REST API in Workers (counts against rate limit)
111const client = new Cloudflare({ apiToken: env.CLOUDFLARE_API_TOKEN });
112const zones = await client.zones.list();
113 
114// ✅ CORRECT - Use bindings (no rate limit)
115// Access via env.MY_BINDING
116```
117 
118## Authentication Errors (401)
119 
120**Problem:** "Authentication failed" or "Invalid token"
121 
122**Causes:**
123- Token expired
124- Token deleted/revoked
125- Token not set in environment
126- Wrong token format
127 
128**Solution:**
129 
130```typescript
131// Verify token is set
132if (!process.env.CLOUDFLARE_API_TOKEN) {
133  throw new Error('CLOUDFLARE_API_TOKEN not set');
134}
135 
136// Test token
137const user = await client.user.tokens.verify();
138console.log('Token valid:', user.status);
139```
140 
141## Timeout Errors
142 
143**Problem:** Request times out (default 60s).
144 
145**Cause:** Large operations (bulk DNS, zone transfers).
146 
147**Solution:** Increase timeout or split operations.
148 
149```typescript
150// Increase timeout
151const client = new Cloudflare({
152  timeout: 300000, // 5 minutes
153});
154 
155// Or split operations
156const batchSize = 100;
157for (let i = 0; i < records.length; i += batchSize) {
158  const batch = records.slice(i, i + batchSize);
159  await processBatch(batch);
160}
161```
162 
163## Zone Not Found (404)
164 
165**Problem:** Zone ID valid but returns 404.
166 
167**Causes:**
168- Zone not in account associated with token
169- Zone deleted
170- Wrong zone ID format
171 
172**Solution:**
173 
174```typescript
175// List all zones to find correct ID
176for await (const zone of client.zones.list()) {
177  console.log(zone.id, zone.name);
178}
179```
180 
181## Limits Reference
182 
183| Resource/Limit | Value | Notes |
184|----------------|-------|-------|
185| API rate limit | 1200/5min | Per user/token |
186| IP rate limit | 200/sec | Per IP |
187| GraphQL rate limit | 320/5min | Cost-based |
188| Parallel requests (recommended) | < 10 | Avoid overwhelming API |
189| Default page size | 20 | Use auto-pagination |
190| Max page size | 50 | Some endpoints |
191 
192## Best Practices
193 
194**Security:**
195- Never commit tokens
196- Use minimal permissions
197- Rotate tokens regularly
198- Set token expiration
199 
200**Performance:**
201- Batch operations
202- Use pagination wisely
203- Cache responses
204- Handle rate limits
205 
206**Code Organization:**
207 
208```typescript
209// Create reusable client instance
210export const cfClient = new Cloudflare({
211  apiToken: process.env.CLOUDFLARE_API_TOKEN,
212  maxRetries: 5,
213});
214 
215// Wrap common operations
216export async function getZoneDetails(zoneId: string) {
217  return await cfClient.zones.get({ zone_id: zoneId });
218}
219```
220 
221## See Also
222 
223- [api.md](./api.md) - Error types, authentication
224- [configuration.md](./configuration.md) - Timeout/retry configuration
225- [patterns.md](./patterns.md) - Error handling patterns
226