Error Codes Reference

​

Request and routing errors

​

ERR_NGROK_27228

• The request body is not valid JSON
• A required field is missing for the API surface you called
• A field holds a value the surface does not accept

• Check the reason in the message for the offending field
• Verify the body matches the API surface you posted to, whether Chat Completions, Responses, Messages, or the native Gemini surface

​

ERR_NGROK_27224

• The model ID is misspelled
• The model is not in the model catalog and no custom provider defines it

• Check the suggestion in the message, which names the closest catalog match
• Look the model up in the model catalog
• Qualify the model with its provider, such as openai:gpt-4o. See Choose a model

​

ERR_NGROK_27225

• The provider prefix is misspelled
• The provider is a custom provider that does not exist on your account

• List your providers with the Providers API
• Register the custom provider before routing to it

​

ERR_NGROK_27230

• A provider-qualified model name whose prefix is neither a known provider nor part of a real model ID

• Use provider:model, with the provider exactly as the Providers API reports it
• Drop the prefix to let the gateway resolve the model from the catalog

​

ERR_NGROK_27229

• The model field is empty, or holds more separators than provider:model allows

• Send either a bare model ID or a single provider:model pair

​

ERR_NGROK_27204

• The request path is not one the gateway serves

• Post to /v1/chat/completions, /v1/responses, /v1/messages, /v1/decisions, /v1/systemone, /v1/files, the native Gemini path /v1beta/models/{model}:generateContent, or /v1beta/interactions
• The gateway does not serve /v1/embeddings, /v1/completions, or image and audio endpoints
• Point your SDK’s base URL at https://gateway.ngrok.ai/v1 rather than a full endpoint path

​

ERR_NGROK_27226

• The provider has no equivalent of the surface you called, such as the Responses API on a provider that only serves Chat Completions

• Call the surface the provider supports. See the provider’s page under Getting Started With
• Choose a different provider for that surface

​

ERR_NGROK_27205

• The gateway knows this endpoint but doesn’t support it yet

• Use a supported endpoint such as /v1/chat/completions. See ERR_NGROK_27204 for the full list

​

ERR_NGROK_27250

• An Interactions API request set store to true

• Omit store, or set it to false. See Google SDK

​

Access policy errors

​

ERR_NGROK_27231

• The access key’s configuration does not include the provider in its access scope

• Allow the provider in the key’s access key configuration
• See Restrict providers and models for how scope is evaluated

​

ERR_NGROK_27232

• The configuration’s access scope excludes the model, even though the provider is allowed

• Add the model to the access scope in the key’s access key configuration

​

Credential and credit errors

​

ERR_NGROK_27201

• No access key in the request
• The access key is malformed, revoked, or deleted

• Send your access key as Authorization: Bearer ng-xxxxx-g1-xxxxx, or as x-api-key on the Anthropic surface and X-Goog-Api-Key on the native Gemini surface
• Confirm the key still exists with the Access Keys API

​

ERR_NGROK_27202

• The access key’s configuration has no routing credentials for the requested provider
• Every provider key the configuration referenced was deleted

• Add a routing rule for the provider in the key’s access key configuration
• Attach a provider key, or pay with credits where the provider supports it

​

ERR_NGROK_27206

• The account’s credit balance is zero or below, or billing is not set up for the account yet
• Every request needs credits, even with your own provider keys, because each one pays a small processing fee

• Check your balance with the Credits API
• Purchase credits. Your own provider key does not bypass this check

​

ERR_NGROK_27233

• The model isn’t in the ngrok.ai catalog, so ngrok.ai has no price for it

• Attach your own provider key for that provider
• Pick a catalog model instead. See the model catalog

​

ERR_NGROK_27239

• You can’t pay for this model with credits on that provider right now

• Retry, or fail over to another model. See Configure fallback models
• Attach your own provider key for that provider

​

ERR_NGROK_27236

• You can’t pay for this model with credits on that provider yet, because ngrok.ai doesn’t have a price for it

• Attach your own provider key for that provider
• Pick another model from the model catalog

​

ERR_NGROK_27238

• The request uses a feature, such as a hosted tool, that you can’t pay for with credits on that model

• Remove the feature from the request
• Attach your own provider key for that provider

​

ERR_NGROK_27249

• The model exists in the catalog, but you can’t pay for it with credits on that provider

• Attach your own provider key for that provider
• Pick a model you can pay for with credits. See the model catalog

​

ERR_NGROK_27240

• The request uses a file that wasn’t uploaded from your account, so you can’t pay for it with credits

• Attach your own provider key to use files stored in your provider account

​

Upstream failures

​

ERR_NGROK_27211

• The provider key stored in ngrok is invalid, revoked, or rotated at the provider

• Rotate the provider key to the current value
• Verify the key directly against the provider

​

ERR_NGROK_27217

• Every credential and candidate the gateway tried was rate limited

• Attach more provider keys so the gateway has another credential to try
• Add candidates from other providers. See Multi-provider failover
• Slow your request rate, or raise your quota with the provider

​

ERR_NGROK_27207

• A single upstream attempt exceeded the per-request timeout

• Raise the per-request timeout in Account Settings
• Shorten the prompt, or choose a faster model

​

ERR_NGROK_3810

• Every attempt together exceeded the total timeout
• Too many slow candidates in the failover list

• Raise the total timeout in Account Settings
• Lower the per-request timeout so a slow provider fails sooner and leaves budget for the next candidate
• Reduce the number of failover candidates

​

ERR_NGROK_27227

• None of the models in the request could be used, for example because the access key can’t reach them
• With ngrok/auto, none of the models the key can reach are available for automatic selection. See Automatic model selection

• Confirm the configuration’s routing rules cover the provider you requested
• See Handle gateway errors for the order the gateway tries models in

​

ERR_NGROK_27237

• A custom provider’s base URL points back at the AI Gateway

• Point the custom provider at its real upstream. See Use a model you run yourself

​

Limit errors

​

ERR_NGROK_3811

• The prompt and context exceed the account’s max input tokens
• Very long conversation history, or large embedded content in messages

• Reduce the prompt length or conversation history
• Raise or clear maxInputTokens in Account Settings
• Count tokens client-side before sending

​

ERR_NGROK_AI_GATEWAY_REQUEST_BODY_TOO_LONG

• The request body is larger than 32 MiB

• Upload large documents and images with the Files API instead of sending them inline
• Reduce the conversation history or embedded content

​

Retired setup

​

ERR_NGROK_3820

AI Gateway has a new home at https://app.ngrok.ai. The old ai-gateway traffic
policy action has been retired. Existing credits have been migrated to
https://app.ngrok.ai. If you have any questions or issues, please reach out to
support@ngrok.com.

• A Traffic Policy still contains the retired ai-gateway action

• Remove the ai-gateway action from the endpoint’s Traffic Policy
• Send LLM traffic to https://gateway.ngrok.ai with an access key instead, and manage the gateway at app.ngrok.ai
• Credits from the retired setup were migrated automatically. Email support@ngrok.com if your balance looks wrong

​

Other codes

​

SDK error handling

from openai import OpenAI, APIError

client = OpenAI(
    base_url="https://gateway.ngrok.ai/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_27224" in str(e):
        print("Model not found - check model name spelling")

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.ngrok.ai/v1',
  apiKey: 'ng-xxxxx-g1-xxxxx',
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.log('Status:', error.status);
    console.log('Message:', error.message);
    if (error.message.includes('ERR_NGROK_27224')) {
      console.log('Model not found - check model name spelling');
    }
  }
}

​

Next steps