davila7/claude-code-templates / cli-tool/components/skills/development/cloudflare-deploy
cloudflare-deploy
FlaggedDeploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
references/api/gotchas.md
View on GitHub# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |