329 Gotchas 82fd16d6

# Gotchas & Troubleshooting

## Rate Limits & 429 Errors

**Actual Limits:**

- **1200 requests / 5 minutes** per user/token (global)
- **200 requests / second** per IP address
- **GraphQL: 320 / 5 minutes** (cost-based)

**SDK Behavior:**

- Auto-retry with exponential backoff (default 2 retries, Go: 10)
- Respects `Retry-After` header
- Throws `RateLimitError` after exhausting retries

**Solution:**

```typescript
// Increase retries for rate-limit-heavy workflows
const client = new Cloudflare({ maxRetries: 5 })

// Add application-level throttling
import pLimit from 'p-limit'
const limit = pLimit(10) // Max 10 concurrent requests
```

## SDK-Specific Issues

### Go: Required Field Wrapper

**Problem:** Go SDK requires `cloudflare.F()` wrapper for optional fields.

```go
// ❌ WRONG - Won't compile or send field
client.Zones.New(ctx, cloudflare.ZoneNewParams{
    Name: "example.com",
})

// ✅ CORRECT
client.Zones.New(ctx, cloudflare.ZoneNewParams{
    Name: cloudflare.F("example.com"),
    Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{
        ID: cloudflare.F("account-id"),
    }),
})
```

**Why:** Distinguishes between zero value, null, and omitted fields.

### Python: Async vs Sync Clients

**Problem:** Using sync client in async context or vice versa.

```python
# ❌ WRONG - Can't await sync client
from cloudflare import Cloudflare
client = Cloudflare()
await client.zones.list()  # TypeError

# ✅ CORRECT - Use AsyncCloudflare
from cloudflare import AsyncCloudflare
client = AsyncCloudflare()
await client.zones.list()
```

## Token Permission Errors (403)

**Problem:** API returns 403 Forbidden despite valid token.

**Cause:** Token lacks required permissions (scope).

**Scopes Required:**

| Operation     | Required Scope                          |
| ------------- | --------------------------------------- |
| List zones    | Zone:Read (zone-level or account-level) |
| Create zone   | Zone:Edit (account-level)               |
| Edit DNS      | DNS:Edit (zone-level)                   |
| Deploy Worker | Workers Script:Edit (account-level)     |
| Read KV       | Workers KV Storage:Read                 |
| Write KV      | Workers KV Storage:Edit                 |

**Solution:** Re-create token with correct permissions in Dashboard → My Profile → API Tokens.

## Pagination Truncation

**Problem:** Only getting first 20 results (default page size).

**Solution:** Use auto-pagination iterators.

```typescript
// ❌ WRONG - Only first page (20 items)
const page = await client.zones.list()

// ✅ CORRECT - All results
const zones = []
for await (const zone of client.zones.list()) {
  zones.push(zone)
}
```

## Workers Subrequests

**Problem:** Rate limit hit faster than expected in Workers.

**Cause:** Workers subrequests count as separate API calls.

**Solution:** Use bindings instead of REST API in Workers (see ../bindings/).

```typescript
// ❌ WRONG - REST API in Workers (counts against rate limit)
const client = new Cloudflare({ apiToken: env.CLOUDFLARE_API_TOKEN })
const zones = await client.zones.list()

// ✅ CORRECT - Use bindings (no rate limit)
// Access via env.MY_BINDING
```

## Authentication Errors (401)

**Problem:** "Authentication failed" or "Invalid token"

**Causes:**

- Token expired
- Token deleted/revoked
- Token not set in environment
- Wrong token format

**Solution:**

```typescript
// Verify token is set
if (!process.env.CLOUDFLARE_API_TOKEN) {
  throw new Error('CLOUDFLARE_API_TOKEN not set')
}

// Test token
const user = await client.user.tokens.verify()
console.log('Token valid:', user.status)
```

## Timeout Errors

**Problem:** Request times out (default 60s).

**Cause:** Large operations (bulk DNS, zone transfers).

**Solution:** Increase timeout or split operations.

```typescript
// Increase timeout
const client = new Cloudflare({
  timeout: 300000, // 5 minutes
})

// Or split operations
const batchSize = 100
for (let i = 0; i < records.length; i += batchSize) {
  const batch = records.slice(i, i + batchSize)
  await processBatch(batch)
}
```

## Zone Not Found (404)

**Problem:** Zone ID valid but returns 404.

**Causes:**

- Zone not in account associated with token
- Zone deleted
- Wrong zone ID format

**Solution:**

```typescript
// List all zones to find correct ID
for await (const zone of client.zones.list()) {
  console.log(zone.id, zone.name)
}
```

## Limits Reference

| Resource/Limit                  | Value     | Notes                  |
| ------------------------------- | --------- | ---------------------- |
| API rate limit                  | 1200/5min | Per user/token         |
| IP rate limit                   | 200/sec   | Per IP                 |
| GraphQL rate limit              | 320/5min  | Cost-based             |
| Parallel requests (recommended) | < 10      | Avoid overwhelming API |
| Default page size               | 20        | Use auto-pagination    |
| Max page size                   | 50        | Some endpoints         |

## Best Practices

**Security:**

- Never commit tokens
- Use minimal permissions
- Rotate tokens regularly
- Set token expiration

**Performance:**

- Batch operations
- Use pagination wisely
- Cache responses
- Handle rate limits

**Code Organization:**

```typescript
// Create reusable client instance
export const cfClient = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
  maxRetries: 5,
})

// Wrap common operations
export async function getZoneDetails(zoneId: string) {
  return await cfClient.zones.get({ zone_id: zoneId })
}
```

## See Also

- [api.md](./api.md) - Error types, authentication
- [configuration.md](./configuration.md) - Timeout/retry configuration
- [patterns.md](./patterns.md) - Error handling patterns