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

​

ERR_NGROK_4026

• Your AI Gateway credit balance has reached zero
• Credits have expired

• Purchase additional credits to restore access
• See Credits for details on credit management

​

ERR_NGROK_6033

• Your account does not have AI Gateway credits
• You haven’t purchased credits yet

• Purchase credits (minimum $5.00)
• See Credits for details

​

ERR_NGROK_27001

• Your account plan does not support AI Gateway API Keys
• The AI Gateway API Keys feature is not enabled for your account

• Upgrade to the Pay-as-you-go plan
• Contact ngrok support if you believe this is an error

​

ERR_NGROK_27002

• The endpoint_id provided when creating an AI Gateway API Key does not exist
• The endpoint was deleted

• Verify the endpoint ID exists: ngrok api endpoints list
• Use the correct endpoint ID when creating a key

​

ERR_NGROK_27003

• The endpoint exists but does not have the ai-gateway Traffic Policy action configured

• Add the ai-gateway action to the endpoint’s Traffic Policy
• See Creating Endpoints for setup instructions

​

ERR_NGROK_27004

• The description field in the create or update request exceeds 255 characters

• Shorten the description to 255 characters or fewer

​

ERR_NGROK_27005

• The metadata field in the create or update request exceeds 4096 characters

• Shorten the metadata to 4096 characters or fewer

​

ERR_NGROK_27006

• A required field was not provided when creating an AI Gateway API Key
• Most commonly, endpoint_id is missing

• Include the endpoint_id field when creating a key:
  Report incorrect code

  Copy

  Ask AI

  ngrok api ai-gateway-api-keys create --endpoint-id ep_xxxxx
  

​

ERR_NGROK_27007

• The AI Gateway API Key token is incorrect or has been deleted
• The key format is ng-*-g1-* but the token doesn’t match any existing key

• Verify you’re using the correct AI Gateway API Key token
• Check if the key was deleted—list keys with ngrok api ai-gateway-api-keys list
• Create a new key if needed—tokens are only shown once at creation time

​

ERR_NGROK_27008

• The AI Gateway API Key was created for a different endpoint
• Each key is scoped to a specific AI Gateway endpoint via endpoint_id

• Use the correct AI Gateway API Key for this endpoint
• Create a new key scoped to this endpoint: ngrok api ai-gateway-api-keys create --endpoint-id <this-endpoint-id>

​

ERR_NGROK_27009

• Temporary issue validating the API key
• Key validation service is temporarily unavailable

• Retry the request after a short delay
• If the issue persists, contact ngrok support

​

SDK error handling

from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://your-ai-gateway.ngrok.app/v1",
    api_key="ng-xxxxx-g1-xxxxx"
)

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