Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.11
references/ai-gateway/troubleshooting.mdMarkdown2 KBView on GitHub
| Error | Cause | Fix |
|---|---|---|
| 401 | Missing cf-aig-authorization header | Add header with CF API token |
| 403 | Invalid provider key / BYOK expired | Check provider key in dashboard |
| 429 | Rate limit exceeded | Increase limit or implement backoff |
const client = new OpenAI({
baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,
defaultHeaders: { 'cf-aig-authorization': `Bearer ${CF_API_TOKEN}` }
});async function requestWithRetry(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try { return await fn(); }
catch (e) {
if (e.status === 429 && i < maxRetries - 1) {
await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
continue;
}
throw e;
}
}
}| Issue | Reality |
|---|---|
| Metadata limits | Max 5 entries, flat only (no nesting) |
| Cache key collision | Use unique keys per expected response |
| BYOK + Unified Billing | Mutually exclusive |
| Rate limit scope | Per-gateway, not per-user (use dynamic routing for per-user) |
| Log delay | 30-60 seconds normal |
| Streaming + caching | Incompatible |
| Model name (unified API) | Prefix required: openai/gpt-4o, not gpt-4o |
Causes:
Check: response.headers.get('cf-aig-cache-status') → HIT or MISS
cf-aig-collect-log: false header# Test connectivity
curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \
-H "Authorization: Bearer $OPENAI_KEY" \
-H "cf-aig-authorization: Bearer $CF_TOKEN"// Check response headers
console.log('Cache:', response.headers.get('cf-aig-cache-status'));
console.log('Request ID:', response.headers.get('cf-ray'));Dashboard → AI Gateway → Select gateway
Metrics: Requests, tokens, latency (p50/p95/p99), cache hit rate, costs
Log filters: status: error, provider: openai, cost > 0.01, duration > 1000
Export: Logpush to S3/GCS/Datadog/Splunk