1# Gotchas & Best Practices
2 
3## Fit Modes
4 
5| Mode | Best For | Behavior |
6|------|----------|----------|
7| `cover` | Hero images, thumbnails | Fills space, crops excess |
8| `contain` | Product images, artwork | Preserves full image, may add padding |
9| `scale-down` | User uploads | Never enlarges |
10| `crop` | Precise crops | Uses gravity |
11| `pad` | Fixed aspect ratio | Adds background |
12 
13## Format Selection
14 
15```typescript
16format: 'auto' // Recommended - negotiates best format
17```
18 
19**Support:** AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)
20 
21## Quality Settings
22 
23| Use Case | Quality |
24|----------|---------|
25| Thumbnails | 75-80 |
26| Standard | 85 (default) |
27| High-quality | 90-95 |
28 
29## Common Errors
30 
31### 5403: "Image transformation failed"
32- Verify `width`/`height` ≤ 12000
33- Check `quality` 1-100, `dpr` 1-3
34- Don't combine incompatible options
35 
36### 9413: "Rate limit exceeded"
37Implement caching and exponential backoff:
38```typescript
39for (let i = 0; i < 3; i++) {
40  try { return await env.IMAGES.input(buffer).transform({...}).output(); }
41  catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }
42}
43```
44 
45### 5401: "Image too large"
46Pre-process images before upload (max 100MB, 12000×12000px)
47 
48### 5400: "Invalid image format"
49Supported: JPEG, PNG, GIF, WebP, AVIF, SVG
50 
51### 401/403: "Unauthorized"
52Verify API token has `Cloudflare Images → Edit` permission
53 
54## Limits
55 
56| Resource | Limit |
57|----------|-------|
58| Max input size | 100MB |
59| Max dimensions | 12000×12000px |
60| Quality range | 1-100 |
61| DPR range | 1-3 |
62| API rate limit | ~1200 req/min |
63 
64## AVIF Gotchas
65 
66- **Slower encoding**: First request may have higher latency
67- **Browser detection**:
68```typescript
69const format = /image\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';
70```
71 
72## Anti-Patterns
73 
74```typescript
75// ❌ No caching - transforms every request
76return env.IMAGES.input(buffer).transform({...}).output().response();
77 
78// ❌ cover without both dimensions
79transform({ width: 800, fit: 'cover' })
80 
81// ✅ Always set both for cover
82transform({ width: 800, height: 600, fit: 'cover' })
83 
84// ❌ Exposes API token to client
85// ✅ Use Direct Creator Upload (patterns.md)
86```
87 
88## Debugging
89 
90```typescript
91// Check response headers
92console.log('Content-Type:', response.headers.get('Content-Type'));
93 
94// Test with curl
95// curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif"
96 
97// Monitor logs
98// npx wrangler tail
99```
100