Troubleshooting

​

Error codes reference

​

ERR_NGROK_3800

• Network connectivity issues between ngrok and the provider
• Provider endpoint is down or unreachable
• DNS resolution failure for provider URL

• Check provider status pages (for example, OpenAI Status)
• Verify custom provider base_url is correct and accessible
• Configure failover to alternative providers

​

ERR_NGROK_3801

• Request body is not valid JSON
• model field is not a string
• models field is not an array
• models array contains non-string values

• Validate your request JSON before sending
• Ensure the model field is a string
• If using models array, ensure all entries are strings

​

ERR_NGROK_3802

• No Authorization header in the client request
• No API keys configured for the provider in the gateway
• API key selection strategy filtered out all keys

• Include an API key in your request: Authorization: Bearer sk-xxx
• Configure API keys in your gateway’s provider configuration
• Review your api_key_selection strategy if configured

​

ERR_NGROK_3803

• CEL expression syntax error in model_selection.strategy
• Runtime error evaluating the strategy expression
• Reference to undefined variable in strategy

• Check variable names and ensure they are available and correctly referenced.
• Check for typos in variable names (for example, ai.models not ai.model)
• Review CEL Functions Reference for available functions.
• Try and validate your CEL expressions using the CEL playground.

​

ERR_NGROK_3804

• Typo in the model name (for example, gpt-4a instead of gpt-4o)
• Model not in the Model Catalog and no provider prefix
• only_allow_configured_models: true and model not in provider config
• only_allow_configured_providers: true and provider not configured

• Check your spelling. Common models include gpt-4o, gpt-4, claude-3-5-sonnet-20241022
• For unknown models, prefix with provider: (for example, openai:custom-model)
• Review your gateway’s providers configuration
• Check if restriction flags only_allow_configured_models or only_allow_configured_providers are excluding the model you are trying to use

​

ERR_NGROK_3805

• A strategy either returned empty, had an error, or returned models not in the catalog or matched the client’s requested models. The gateway tries each in order and fails immediately if it encounters an error or an empty set, and after exhausting all of them.

• Double check your model selection strategies and ensure they are correctly configured to return models that exist in the catalog or in your gateway configuration
• Double check whether you have enabled only_allow_configured_models or only_allow_configured_providers
• If clients specify models in requests, ensure your model selection strategies will return those models

​

ERR_NGROK_3806

• Strategy expression returned a string, number, or other value instead of a model object or list of model objects

• Use ai.models, ai.models.randomize(), ai.models.random(), or ai.models.filter() which return model objects
• Don’t return raw strings like "gpt-4o" or numbers like 123 from your strategy expressions

​

ERR_NGROK_3807

• All configured providers returned errors
• All API keys exhausted (rate limits, invalid keys)
• Network issues to all providers
• Provider-specific errors (invalid model, authentication failures)

• Check the error details for specific provider failures (errors are listed in the response)
• Verify API keys are valid and have available quota
• Add more providers or API keys for better failover
• Use debugging to inspect individual attempt errors

​

ERR_NGROK_3808

• No API key sent in request and no API keys configured for the provider (only for official providers like OpenAI)
• All api_key_selection strategies returned no keys or had errors
• Strategy expression returned an invalid type instead of a key or list of keys

• Include an API key in your request: Authorization: Bearer sk-xxx
• Configure API keys in your gateway’s provider configuration
• Check the error message for details about which strategy failed

​

ERR_NGROK_3809

• AI Gateway action used on a non-HTTP endpoint
• Endpoint configured for TCP or TLS protocol

• AI Gateway only supports HTTP/HTTPS endpoints
• Check your endpoint configuration and ensure it uses HTTP protocol

​

ERR_NGROK_3810

• All failover attempts took longer than total_timeout
• Providers responding slowly
• Too many failover candidates with slow responses

• Increase total_timeout if appropriate for your use case
• Reduce per_request_timeout to fail faster on slow providers
• Use model selection strategies to prioritize faster providers
• Reduce the number of failover candidates

​

ERR_NGROK_3811

• Prompt and context exceed max_input_tokens setting
• Very long conversation history
• Large embedded content in messages

• Reduce prompt length or conversation history
• Increase max_input_tokens in gateway configuration
• Implement client-side token counting or compression before sending

​

SDK error handling

from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://your-gateway.ngrok.app/v1",
    api_key="your-key"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIError as e:
    print(f"Error code: {e.code}")
    print(f"Message: {e.message}")
    if "ERR_NGROK_3804" in str(e):
        print("Model not found - check model name spelling")

​

Next steps