1## Best Practices Summary
2 
3**Smart Shield Note:** Argo Smart Routing evolving into Smart Shield. Best practices below remain applicable; monitor Cloudflare changelog for Smart Shield updates.
4 
51. **Always check editability** before attempting to enable/disable Argo
62. **Set up billing notifications** to avoid unexpected costs
73. **Combine with Tiered Cache** for maximum performance benefit
84. **Use in production only** - disable for dev/staging to control costs
95. **Monitor analytics** - require 500+ requests in 48h for detailed metrics
106. **Handle errors gracefully** - check for billing, permissions, zone compatibility
117. **Test configuration changes** in staging before production
128. **Use TypeScript SDK** for type safety and better developer experience
139. **Implement retry logic** for API calls in production systems
1410. **Document zone-specific settings** for team visibility
15 
16## Common Errors
17 
18### "Argo unavailable"
19 
20**Problem:** API returns error "Argo Smart Routing is unavailable for this zone"
21 
22**Cause:** Zone not eligible or billing not set up
23 
24**Solution:**
251. Verify zone has Enterprise or higher plan
262. Check billing is configured in Account → Billing
273. Ensure payment method is valid and current
284. Contact Cloudflare support if eligibility unclear
29 
30### "Cannot enable/disable"
31 
32**Problem:** API call succeeds but status remains unchanged, or `editable: false` in GET response
33 
34**Cause:** Insufficient permissions or zone restrictions
35 
36**Solution:**
371. Check API token has `Zone:Argo Smart Routing:Edit` permission
382. Verify `editable: true` in GET response before attempting PATCH
393. If `editable: false`, check:
40   - Billing configured for account
41   - Zone plan includes Argo (Enterprise+)
42   - No active zone holds or suspensions
43   - API token has correct scopes
44 
45### `editable: false` Error
46 
47**Problem:** GET request returns `"editable": false`, preventing enable/disable
48 
49**Cause:** Zone-level restrictions from billing, plan, or permissions
50 
51**Solution Pattern:**
52```typescript
53const status = await client.argo.smartRouting.get({ zone_id: zoneId });
54 
55if (!status.editable) {
56  // Don't attempt to modify - will fail
57  console.error('Cannot modify Argo settings:');
58  console.error('- Check billing is configured');
59  console.error('- Verify zone has Enterprise+ plan');
60  console.error('- Confirm API token has Edit permission');
61  throw new Error('Argo is not editable for this zone');
62}
63 
64// Safe to proceed with enable/disable
65await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
66```
67 
68### Rate Limiting
69 
70**Problem:** `429 Too Many Requests` error from API
71 
72**Cause:** Exceeded API rate limits (typically 1200 requests per 5 minutes)
73 
74**Solution:**
75```typescript
76import { RateLimitError } from 'cloudflare';
77 
78try {
79  await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
80} catch (error) {
81  if (error instanceof RateLimitError) {
82    const retryAfter = error.response?.headers.get('retry-after');
83    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
84    
85    // Implement exponential backoff
86    await new Promise(resolve => setTimeout(resolve, (retryAfter || 60) * 1000));
87    // Retry request
88  }
89}
90```
91 
92## Limits
93 
94| Resource/Limit | Value | Notes |
95|----------------|-------|-------|
96| Min requests for analytics | 500 in 48h | For detailed metrics via GraphQL |
97| Zones supported | Enterprise+ | Check zone plan in dashboard |
98| Billing requirement | Must be configured | Before enabling; verify payment method |
99| API rate limit | 1200 req / 5 min | Per API token across all endpoints |
100| Spectrum apps | No hard limit | Each app can enable Argo independently |
101| Traffic counting | Proxied only | Only orange-clouded DNS records count |
102| DDoS/WAF exemption | Yes | Mitigated traffic excluded from billing |
103| Analytics latency | 1-5 minutes | Real-time metrics not available |
104 
105## Additional Resources
106 
107- [Official Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)
108- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)
109- [API Authentication](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
110- [Cloudflare TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)
111- [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python)
112