Troubleshooting (29)

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

Authentication errors

401 or unauthenticated errors

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

  1. Verify header placement: On provider-native endpoints, put your Cloudflare token in cf-aig-authorization. Supply provider credentials in the format AI Gateway recognizes for the provider and endpoint. For example, Anthropic Messages requires x-api-key, while OpenAI uses Authorization: Bearer.
  2. Check your configuration based on endpoint type:
  3. 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.
  4. 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.
  5. Verify BYOK key selection: If you have multiple keys configured for a provider, ensure either:
  6. You are using the key with alias default, or
  7. You include the cf-aig-byok-alias header with the correct alias name
  8. Verify BYOK configuration: If using BYOK, confirm in the dashboard that your credentials were saved correctly.

For provider-specific authentication issues:

400: Provider credentials required (2044)

AI Gateway returns HTTP 400 with error code 2044 and the message Customer-provided provider credentials are required for this request when it cannot find applicable provider credentials and Unified Billing fallback is blocked.

Fallback is blocked when Require provider credentials is on for the gateway or the request includes cf-aig-no-wholesale: true. Credentials supplied with the request or an applicable stored BYOK key can satisfy this requirement.

To resolve the error:

  • Supply your provider key using the recognized credential format.
  • For Anthropic Messages ( /anthropic/v1/messages), send x-api-key: <PROVIDER_API_KEY>. AI Gateway does not recognize Authorization: Bearer as provider credentials on this endpoint.
  • If using stored BYOK keys, verify gateway authentication and the key alias. Use default, or select an applicable alias with cf-aig-byok-alias on provider-native requests.

DLP issues

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

Request failures

Requests timing out

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

Requests returning errors from the provider

  • 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

Caching issues

Requests not being cached

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

Unexpected cache hits or misses

Was this helpful?

YesNo

On this page

Troubleshooting (29) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-gateway/reference/troubleshooting/#page","headline":"Troubleshooting","description":"Resolve common AI Gateway issues including authentication errors, missing logs, and provider connectivity problems.","url":"https://developers.cloudflare.com/ai-gateway/reference/troubleshooting/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-gateway/reference/troubleshooting/og.png?v=e2e9a70e6ecb8b47","dateModified":"2026-10-27","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Track the latest updates, new features, and fixes for AI Gateway. title: Changelog image: https://developers.cloudflare.com/ai-gateway/changelog/og.png?v=9c3aed7c656f5118

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-gateway/llms.txt
Use this file to discover all available pages before exploring further.