AI Gateway: FAQs & Troubleshooting
Answers to common AI Gateway questions, and fixes for unsaved changes, unavailable models, and failed model calls.
This page answers common questions about model families, providers, tiers, and keys in AI Gateway. Use the troubleshooting entries when a change doesn't stick, a model isn't offered, or a model call fails.
FAQs
Families and tiers
Who can configure AI Gateway?
Configure the AI Gateway: Account Admin and Organisation Admin. Use the AI Gateway: Developer, Governance Manager, Account Admin, and Organisation Admin. See Roles.
Does AI Gateway apply to one project or the whole account?
The whole account. Family availability, credentials, and tier mappings apply to all account activity. See AI Gateway.
Why do agents request a tier instead of a model?
So you can change the model without editing agents. A tier, Economy, Smart, or Premium, resolves to whichever model the family maps to it. Remap the tier and every agent that asks for it picks up the change. See Model tiers.
What is the default family for?
It serves any request that doesn't name a family. Exactly one enabled family is the default; setting a new default removes the previous one, and the change applies only after you save. See Model families.
Are Gemini and Google different families?
No. Gateway Settings labels the family Gemini; Model Catalog labels it Google. See Gateway Settings.
Do agents' background calls follow my tier mappings?
Yes. Knowledge queries, document summaries and classification, and conversation titles ask for a tier, so remapping a tier changes them too. See What routes through the gateway.
Can every family be used by agents?
No. Agents can use the Google (Gemini) and OpenAI families. Other families, such as Anthropic, aren't offered for agents in production yet; where they appear, they're marked Dev only. See Model families for agents.
Keys and billing
What's the difference between a UPTIQ managed key and Bring your own key?
With a UPTIQ managed key, the platform holds and pays for the key, and usage counts against your credit balance. With Bring your own key, your organization's key is used and the provider bills you directly. One family can mix both. See Gateways and credentials.
Where are my own provider keys stored, and can I read one back?
In the deployment's cloud secret manager, GCP Secret Manager or Azure Key Vault. Keys are write-only: nobody can read one back through the UI or the API. To rotate one, enter the new key against the same provider. See Where your own keys are stored.
When should I use OpenRouter?
OpenRouter uses your organization's own OpenRouter key, and chooses the upstream provider itself, so you don't control which one serves a request or where it runs. Where region residency matters, use UPTIQ AI Gateway with your own key against your own provider tenancy. See Choose a gateway.
Can my own applications call AI Gateway?
Yes. Select Connect on Gateway Settings, create a key under Gateway API keys, and send OpenAI-compatible requests with a tier or a model. Only Account Admin and Org Admin can create and revoke gateway keys. See Connect to AI Gateway.
Is a JSON reply guaranteed when I ask for one?
No. A requested format is a preference: if no remaining candidate model can honour it, the call goes ahead without it. Validate the reply's shape yourself. Only OpenAI and Google models enforce a response schema. See Requests for JSON or a response schema.
Can I change provider configuration in Model Catalog?
No. Model Catalog is read-only and reports each provider's status. Change configuration in Gateway Settings with Edit configuration. See Model Catalog.
Troubleshooting
Configuration
My changes to a family disappeared
Save applies to one family at a time, and there's no Save all. Changing families before saving discards pending availability, default, authentication, and tier changes. Make the changes again and select Save before selecting another family. See Save changes.
All three tiers give the same results
They may map to the same model; the product doesn't warn when they do. As shipped, all three Anthropic tiers use Claude Sonnet 4.5. Assign distinct models in Gateway Settings. See Default tier mappings.
A family is missing from Model Catalog
Search hides families with no matching models. Clear the search box, or set the family filter to All families. See Find models.
A family or model isn't offered when building an agent
The agent builder lists only what the gateway can serve: a family it can't serve isn't listed, and a model it can't serve is greyed out. A saved family or model that's no longer available shows as Unavailable. See Model families for agents.
Failed model calls
A call fails because the provider isn't configured
The tier maps to a model whose provider shows Not configured, which fails at request time. In Model Catalog, check that at least one provider for the model is Enabled; if not, configure a key for it in Gateway Settings and save the family. See Diagnose why a model is unavailable.
"The AI provider rate-limited your request" or "is temporarily unavailable"
The gateway retries, then tries the next provider and the family's other models. These messages mean every candidate failed. Try again in a few moments. Enabling more than one provider for a family gives the gateway more paths to the same model. See When a call can't be served first time.
"The LLM provider rejected the request for insufficient credits"
The provider account behind your own key is out of credit. Add credits to the provider account, or lower the requested max_tokens.
"The request exceeds the model context window"
The request is longer than the model accepts. Compare context windows in Model Catalog, and map the tier to a model with a larger window if needed. See Model Catalog.
"The request or response was blocked by a guardrail"
A guardrail stopped the call. Check the agent's guardrails in Agent Config › Guardrails (Beta). Allowed LLM Families and Allowed LLM Providers are always enforced on every model request, and allow only the families you enable here. See Guardrails and Verify the configuration.
I can't create a gateway API key
Only Account Admin and Org Admin can create and revoke gateway keys. See Connect to AI Gateway.
Related
Govern agents and models: every AI Gateway task
Credit Usage: managed-key spend
Maintained by Abhishek Paul
AI-assisted, human-approved
Last updated
Was this helpful?