← Ai Gateway / ai-gateway / reference

Troubleshooting

This page covers common issues when using AI Gateway. For provider-specific troubleshooting, refer to the relevant provider documentation.

If you receive authentication errors from your AI provider, AI Gateway did not pass valid credentials upstream. Check the following:

1. Verify header placement: Make sure your Cloudflare token is in cf-aig-authorization, not Authorization. The Authorization header is reserved for provider credentials.

2. Check your configuration based on endpoint type:

   • Provider-specific endpoints: Confirm your request URL includes the provider path (for example, /google-vertex-ai/ or /openai/). AI Gateway uses this to identify the provider and apply the correct stored credentials.
   • Unified /compat/chat/completions endpoint: Confirm your model name starts with the provider prefix (for example, google-vertex-ai/google/gemini-2.5-flash or openai/gpt-4o). AI Gateway uses this prefix to route the request and select the correct stored credentials.

3. Verify BYOK key selection: If you have multiple keys configured for a provider, ensure either:

   • You are using the key with alias default, or
   • You include the cf-aig-byok-alias header with the correct alias name

4. Verify BYOK configuration: If using BYOK, confirm in the dashboard that your credentials were saved correctly.

For provider-specific authentication issues:

• Google Vertex AI troubleshooting

For troubleshooting Data Loss Prevention issues such as DLP not triggering or unexpected blocking, refer to DLP troubleshooting.

• Check if the upstream provider is experiencing issues
• Consider implementing dynamic routing with fallbacks for transient failures
• Review your rate limiting configuration

• Verify your API key or credentials are valid with the provider directly
• Check the provider's status page for outages
• Review AI Gateway logs for detailed error information

• Verify caching is enabled for your gateway
• Check that the request method and content type are cacheable
• Streaming responses are not cached by default

• Review your cache TTL settings
• Check if you have request headers that are bypassing the cache or setting a custom cache key.