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, or the native Gemini path /v1beta/models/{model}:generateContent
• 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

​

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

​

ERR_NGROK_27001

• The account has no AI Gateway credits
• The AI Gateway feature is not enabled for the account

• Purchase credits (minimum $5.00)
• Contact ngrok support if you believe this is an error

​

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 use ngrok.ai inference where the provider supports it

​

ERR_NGROK_27206

• The request needs an ngrok-managed key and the account’s credit check did not pass

• Check your balance with the Credits API
• Purchase credits, or attach your own provider key so the request bills to the provider instead

​

ERR_NGROK_4026

• The 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_27233

• The model is not in ngrok’s catalog, so ngrok has no pricing to bill it against

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

​

ERR_NGROK_27239

• ngrok’s own capacity for that model and provider is temporarily unavailable

• Retry, or fail over to another model. See Configure fallback models
• Attach your own provider key so the request does not depend on ngrok’s capacity

​

Upstream failures

​

ERR_NGROK_27208

• Every candidate failed, or the request hit the 10-attempt cap

• Read the attempt chain to see what each candidate returned. See Debug failed requests
• Attach more provider keys, or widen the candidate list with fallback models

​

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

• No candidate remained that the gateway could dispatch to

• Confirm the configuration’s routing rules cover the provider you requested
• See Handle gateway errors for how candidates are exhausted

​

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

​

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