Skip to main content

Manage fallback policies in the Admin Console

Enterprise Tier

The Admin Console's Policies → Fallback page shows, per model, what serves a request when that model fails, at every scope at once, and is where fallback is edited without the API. Shipped with the 0.6.0 release.

What a fallback is, and the nine worked configuration scenarios, are on Set up fallback; this page is the Console surface over the same policies. Changes made here apply to live gateway traffic.

How the scopes resolve​

A request resolves its fallback list from the most specific scope that defines one for the requested model:

  1. An API key override, when the key carries one.
  2. A project override otherwise.
  3. The organization default otherwise.

An override can also be Don't fall back: an explicit empty list that stops a key or project from inheriting a broader scope's fallbacks for that model. The API face of the same model is scenario F5 on the scenario page.

Where the page lives​

  • Organization view: Policies → Fallback shows every scope and everything is editable (with the permissions below).
  • Project view: the same page scoped to that project, showing the project's and its keys' overrides. The organization default is shown read-only, with a View in organization link to edit it.

Read the table​

One row per protected model:

  • The row shows the model, the fallback list that applies at the organization default, and a count of project and key overrides.
  • Expanding a row lists each override with an Inherited or Overridden tag, so where a list comes from is visible without opening the editor.
  • A row can show Not available: the model is referenced by a policy but is not currently available to that scope, for example after a catalog change.

Edit a fallback​

  1. In the Admin Console, go to Policies → Fallback (organization view, or inside a project for its scope).
  2. Click Add fallback for a model with none, or Add override on a row to narrow an existing one to a project or an API key.
  3. Order the list under Try in this order, by dragging or with the arrows. The first entry is tried first.
  4. The number of entries is bounded by the scope's attempt limit: the requested model counts as the first attempt, so a limit of 3 leaves room for two fallback entries, and the editor blocks adding more.
  5. Under Retry on, pick which failures walk the chain. The conditions are the five from the field reference. The editor warns that Retry on applies to the whole scope (the entire key, project, or organization), not to the one model being edited.
  6. Save. A disabled Save explains itself in the footer, for example when no fallback entry has been added yet or a selected model is not available to the scope.

Remove a fallback or an override​

  • On a row's ⋯ menu, Remove fallback deletes the model's entry at that scope.
  • Remove override puts a key or project back on the broader scope's list. Inside a project view the same action reads Use organization default.

Test a request​

Test a request shows what would actually run: for a chosen API key or project and a model, it lists the fallback entries that apply, names the scope that supplied each one, and marks a model that is not wired here. It answers the same question as the API's effective-policy view (scenario F7) without leaving the Console.

Who can edit what​

  • Organization administrators manage fallbacks at every scope.
  • Project owners manage their own project's override and the overrides of API keys in that project, and nothing broader. Since 0.6.0 this needs only the project owner's own grants.
  • A control that the signed-in role cannot use is disabled and shows the reason.

Good to know​

  • Only an API key that belongs to a client group in its project can carry a key override. The key picker filters to eligible keys; a management key is capped through a project override instead.
  • Deleting a project deletes its fallback overrides (since 0.6.0), so a project created later with the same ID starts clean.
  • Changes apply to live traffic on the next request; there is no separate publish step.

Terms introduced on this page​

TermMeaning
Client groupA project's grouping of API keys under one client identity (clients.id in the policy API, where a key-scoped target names the group). Key-level fallback overrides attach to keys in a client group.

Where to go next

Set up fallback

What a fallback is, and nine worked scenarios with their API calls.

Improve resilience with fallbacks

The field reference, retry conditions, and per-key configuration.