> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Aliases and fallbacks

> Give a model a stable name your people and apps call, point it at any model you enabled, and list the models to try when it fails.

An alias is a model name your organization defines, such as `default-coding`. Clients send the alias as the model, and the LLM Gateway sends the call to the model it points to. When you change the target, every client follows, with no change on any laptop or in any app.

## Add an alias

1. In [Models](https://platform.xpander.ai/governance/model-access), choose **Add alias** next to **Add provider**.
2. Enter a **Name**: lowercase letters, digits, dots, dashes and underscores, starting with a letter or digit, 63 characters at most. Optionally add a **Description**, such as what it is for.
3. Under **Points to**, pick a model you turned on.
4. Under **Fallbacks, tried in order**, choose **Add a fallback model** for each model to try when the first one fails. The target can't also be a fallback, and each fallback appears once.
5. Choose **Add alias**.

Aliases are listed under **Providers** with **Alias**, **Points to** and **Status**: **Ready**, **Off** (its model is off) or **Fallback off** (a fallback is off). To edit an alias, open it, make your changes and choose **Save alias**. To remove one, choose **Delete alias** in its menu. Clients that still send a deleted alias get an error until they switch to another alias or model.

An alias applies to the whole organization. Each caller is still limited to the models they may use. A person whose groups may not use the alias's model is refused, as they would be when calling that model directly.

Names starting with `xp-` are reserved for xpander. Saving one shows: *Names starting with xp- are xpander's built-in models; choose another name for: ...*

## Fallbacks

A call the provider answers with an overload or a server error is retried on the same model. If it still fails, the gateway tries the alias's first fallback, then the next. Each fallback runs on the key assigned for its own provider ([Whose key pays](/run/llm-gateway/providers-and-keys#whose-key-pays)), and each attempt appears under **Routing** when you open the request in [Logs](https://platform.xpander.ai/governance/logs).

A call refused for a reason that will not change (an invalid request, a model that is off, a budget that is spent) is not retried and does not fall back.

## Where people find aliases

People see your aliases in [AI models & keys](https://chat.xpander.ai/?settings=my-gateway) under **Shortcuts your admin set up**, each with a copy button. Codex, OpenCode and SDK setups offer them in the **Model** picker. On the gateway address, `/v1/models` lists the models and aliases the calling key may use.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.