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: 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:
   • 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

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.

AI Gateway returns HTTP 401 with error code 2009 when the provider rejects the credentials sent with the request or your stored BYOK key. On the /ai/run endpoint and the AI binding, the message starts with Credential error: your credential is invalid or was rejected by the provider, followed by details.

To resolve the error:

• Check with the provider that the key is valid and active.
• Update the key in your request, or update the stored BYOK key in AI Gateway.

If the request uses Unified Billing, AI Gateway returns HTTP 503 instead. Refer to 503: Unified Billing temporarily unavailable (7005).

These errors relate to Unified Billing credits and to payment for requests.

AI Gateway returns HTTP 403 with error code 2049 when it cannot use Unified Billing for the request. AI Gateway checks these causes in order and returns the message for the first one that applies. Each message points to a different fix.

• Gateway authentication is required to use unified billing. Enable authentication on your gateway or provide your own API key (BYOK).

  The gateway does not have authentication turned on. Unified Billing requires an authenticated gateway. Turn on authentication, or use your own provider key with BYOK.

• This request requires customer-provided provider credentials, but no applicable provider key was found.

  Require provider credentials is on for the gateway, or the request includes cf-aig-no-wholesale: true, and no provider key applies to the request. Supply a provider key. For details, refer to 400: Provider credentials required (2044).

• Unified billing is not enabled for this gateway. Provide your own API key (BYOK) or contact Cloudflare support.

  Unified Billing is turned off for the gateway. Use your own provider key with BYOK, or contact Cloudflare Support.

• Insufficient balance; add money to your gateway or use BYOK

  Your account does not have enough credits for the request. Load credits to your account, or use your own provider key with BYOK.

The Insufficient balance message can also come with error code 2021. For low-balance fixes, refer to 402: Insufficient Unified Billing balance (2052).

AI Gateway returns HTTP 402 with error code 2052 when your credit balance is too low for the request. The message has this format:

Insufficient unified billing balance for this request. Your available balance is $<AMOUNT>. Add credits on the AI Gateway Cloudflare dashboard, or use your own provider key (BYOK).

The response also includes an extra object with reason set to insufficient_balance and availableBalanceCents set to your available balance in cents.

To resolve the error:

• Load more credits to your account.
• Set up auto top-up so that your balance does not run out.
• Use your own provider key with BYOK.

AI Gateway returns HTTP 402 with error code 2021 when the request cannot be paid for. There are two cases:

• Payment error from model using BYOK: <DETAILS>

  The provider rejected payment on your own BYOK key. Check the billing status and balance of the key with the provider. To use Unified Billing credits instead, remove the stored key.

• Insufficient balance; add money to your gateway or use BYOK, with the description Insufficient AI Gateway credits

  Your Unified Billing credits ran out. Refer to 402: Insufficient Unified Billing balance (2052).

AI Gateway returns HTTP 429 with error code 2018 when a gateway exceeds the Unified Billing request rate limit. This error is a rate limit, not a balance problem. On the /ai/run endpoint and the AI binding, the message is Unified billing rate limit exceeded for this gateway. Please reduce request rate or use BYOK.

To resolve the error:

• Reduce your request rate, and retry with exponential backoff.
• Use your own provider key with BYOK. The limit does not apply to BYOK requests.

AI Gateway returns HTTP 503 with error code 7005 and the message Unified billing is temporarily unavailable for this provider; retry, or configure your own provider API key (BYOK). when Cloudflare-managed credentials for the provider cannot be used.

To resolve the error:

• Retry the request later.
• Use your own provider key with BYOK.

AI Gateway returns HTTP 403 with error code 2042 and the message AI Gateway is not enabled for this account when AI Gateway access is turned off for your account. To resolve the error, contact Cloudflare Support.

AI Gateway returns HTTP 403 with error code 2036 when the request uses a feature that is not enabled. The general message is This feature is not enabled for this gateway.

If you use Cloudflare Access with a custom domain, the message is AI Gateway Access integration is not enabled for this account.

To resolve the error, contact Cloudflare Support.

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

Error code 7003 is the general bad-request code for AI Gateway. AI Gateway returns it when AI Gateway or the provider rejects a request as invalid and no more specific code applies, and the error message describes the actual problem.

The error message usually has this format:

Model execution failed (User Input Error): <REASON>

If the provider rejected the request, <REASON> is the provider's own error message.

To resolve the error:

• Read the full error message, which usually names the rejected field or value, and fix the request before you retry.
• If you call the model through the AI binding (env.AI.run()), the error may only show AiGatewayError: 7003: User Input Error, with no reason. To see the full error message, send the same request through the REST API.
• If logging or payload collection is turned off, AI Gateway does not store the error message. Record the error response in your application, or turn on logging while you reproduce the problem.

• Check if the upstream provider is experiencing issues
• Consider implementing dynamic routes 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

AI Gateway returns HTTP 500 with error code 2002 and the message Model execution failed (Error) when the provider or AI Gateway fails to process the request.

To resolve the error:

• Retry the request.
• Set up dynamic routing with a fallback model.

AI Gateway returns HTTP 400 with error code 2005 and the message Failed to get response from provider when it does not receive a response from the provider.

To resolve the error:

• Check the provider's status page for outages.
• Retry the request.

• 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.