> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/control-center/ai-gateway/ai-gateway-faqs-and-troubleshooting.md).

# 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

<details>

<summary>Who can configure AI Gateway?</summary>

**Configure the AI Gateway**: Account Admin and Organisation Admin. **Use the AI Gateway**: Developer, Governance Manager, Account Admin, and Organisation Admin. See [Roles](/ai-workbench-qore/control-center/admin/roles.md).

</details>

<details>

<summary>Does AI Gateway apply to one project or the whole account?</summary>

The whole account. Family availability, credentials, and tier mappings apply to all account activity. See [AI Gateway](/ai-workbench-qore/control-center/ai-gateway.md).

</details>

<details>

<summary>Why do agents request a tier instead of a model?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#model-tiers).

</details>

<details>

<summary>What is the default family for?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#model-families).

</details>

<details>

<summary>Are Gemini and Google different families?</summary>

No. Gateway Settings labels the family Gemini; Model Catalog labels it Google. See [Gateway Settings](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#google-and-gemini-refer-to-the-same-family).

</details>

<details>

<summary>Do agents' background calls follow my tier mappings?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#what-routes-through-the-gateway).

</details>

<details>

<summary>Can every family be used by agents?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#model-families-for-agents).

</details>

### Keys and billing

<details>

<summary>What's the difference between a UPTIQ managed key and Bring your own key?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#gateways-and-credentials).

</details>

<details>

<summary>Where are my own provider keys stored, and can I read one back?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#where-your-own-keys-are-stored).

</details>

<details>

<summary>When should I use OpenRouter?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#choose-a-gateway).

</details>

<details>

<summary>Can my own applications call AI Gateway?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#connect-to-ai-gateway).

</details>

<details>

<summary>Is a JSON reply guaranteed when I ask for one?</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#requests-for-json-or-a-response-schema).

</details>

<details>

<summary>Can I change provider configuration in Model Catalog?</summary>

No. Model Catalog is read-only and reports each provider's status. Change configuration in Gateway Settings with **Edit configuration**. See [Model Catalog](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md).

</details>

## Troubleshooting

### Configuration

<details>

<summary>My changes to a family disappeared</summary>

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](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#save-changes).

</details>

<details>

<summary>All three tiers give the same results</summary>

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](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md#default-tier-mappings).

</details>

<details>

<summary>A family is missing from Model Catalog</summary>

Search hides families with no matching models. Clear the search box, or set the family filter to **All families**. See [Find models](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md#find-models).

</details>

<details>

<summary>A family or model isn't offered when building an agent</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#model-families-for-agents).

</details>

### Failed model calls

<details>

<summary>A call fails because the provider isn't configured</summary>

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](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md#diagnose-why-a-model-is-unavailable).

</details>

<details>

<summary>"The AI provider rate-limited your request" or "is temporarily unavailable"</summary>

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](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md#when-a-call-cant-be-served-first-time).

</details>

<details>

<summary>"The LLM provider rejected the request for insufficient credits"</summary>

The provider account behind your own key is out of credit. Add credits to the provider account, or lower the requested `max_tokens`.

</details>

<details>

<summary>"The request exceeds the model context window"</summary>

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](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md#review-model-availability).

</details>

<details>

<summary>"The request or response was blocked by a guardrail"</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/guardrails.md) and [Verify the configuration](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#verify-the-configuration).

</details>

<details>

<summary>I can't create a gateway API key</summary>

Only Account Admin and Org Admin can create and revoke gateway keys. See [Connect to AI Gateway](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md#connect-to-ai-gateway).

</details>

### Related

* [How Model Routing Works](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works.md), [Model Catalog](/ai-workbench-qore/control-center/ai-gateway/model-catalog.md), and [Gateway Settings](/ai-workbench-qore/control-center/ai-gateway/gateway-settings.md)
* [Govern agents and models](/ai-workbench-qore/task-guides/govern-agents-and-models.md#ai-gateway): every AI Gateway task
* [Credit Usage](/ai-workbench-qore/control-center/cost-control/credit-usage.md): managed-key spend

***

{% columns %}
{% column width="83.33333333333334%" %}

<p align="right"><em>Maintained by</em> <mark style="color:green;">Abhishek Paul</mark><br><code>AI-assisted, human-approved</code></p>
{% endcolumn %}

{% column width="16.666666666666664%" %}

<div align="left"><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-d034645b4f8f8ee661985f5306b60ded3289653c%2Fmaintainer-abhishek-paul.png?alt=media" alt="" width="60"></div>
{% endcolumn %}
{% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/ai-workbench-qore/control-center/ai-gateway/ai-gateway-faqs-and-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.