1# AI Gateway Troubleshooting
2 
3## Common Errors
4 
5| Error | Cause | Fix |
6|-------|-------|-----|
7| 401 | Missing `cf-aig-authorization` header | Add header with CF API token |
8| 403 | Invalid provider key / BYOK expired | Check provider key in dashboard |
9| 429 | Rate limit exceeded | Increase limit or implement backoff |
10 
11### 401 Fix
12 
13```typescript
14const client = new OpenAI({
15  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,
16  defaultHeaders: { 'cf-aig-authorization': `Bearer ${CF_API_TOKEN}` }
17});
18```
19 
20### 429 Retry Pattern
21 
22```typescript
23async function requestWithRetry(fn, maxRetries = 3) {
24  for (let i = 0; i < maxRetries; i++) {
25    try { return await fn(); }
26    catch (e) {
27      if (e.status === 429 && i < maxRetries - 1) {
28        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
29        continue;
30      }
31      throw e;
32    }
33  }
34}
35```
36 
37## Gotchas
38 
39| Issue | Reality |
40|-------|---------|
41| Metadata limits | Max 5 entries, flat only (no nesting) |
42| Cache key collision | Use unique keys per expected response |
43| BYOK + Unified Billing | Mutually exclusive |
44| Rate limit scope | Per-gateway, not per-user (use dynamic routing for per-user) |
45| Log delay | 30-60 seconds normal |
46| Streaming + caching | **Incompatible** |
47| Model name (unified API) | Prefix required: `openai/gpt-4o`, not `gpt-4o` |
48 
49## Cache Not Working
50 
51**Causes:**
52- Different request params (temperature, etc.)
53- Streaming enabled
54- Caching disabled in settings
55 
56**Check:** `response.headers.get('cf-aig-cache-status')` → HIT or MISS
57 
58## Logs Not Appearing
59 
601. Check logging enabled: Dashboard → Gateway → Settings
612. Remove `cf-aig-collect-log: false` header
623. Wait 30-60 seconds
634. Check log limit (10M default)
64 
65## Debugging
66 
67```bash
68# Test connectivity
69curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \
70  -H "Authorization: Bearer $OPENAI_KEY" \
71  -H "cf-aig-authorization: Bearer $CF_TOKEN"
72```
73 
74```typescript
75// Check response headers
76console.log('Cache:', response.headers.get('cf-aig-cache-status'));
77console.log('Request ID:', response.headers.get('cf-ray'));
78```
79 
80## Analytics
81 
82Dashboard → AI Gateway → Select gateway
83 
84**Metrics:** Requests, tokens, latency (p50/p95/p99), cache hit rate, costs
85 
86**Log filters:** `status: error`, `provider: openai`, `cost > 0.01`, `duration > 1000`
87 
88**Export:** Logpush to S3/GCS/Datadog/Splunk
89