OpenGatewayDocs
DocsModelsStatusSign In

Fallbacks

Set ordered fallback model IDs with `extra.fallbacks`, learn which provider failures advance to another route, and see how pre-frame streaming retries appear in Logs.

Configure model fallbacks#

extra.fallbacks is an ordered list of model IDs to try after the route candidates for the requested model. OpenGateway resolves each ID for the same API endpoint, so choose fallback models that support that endpoint. Use exact IDs from the model catalog.

This extension is available on routed Chat Completions, Responses, Messages, embeddings, Decisions, and image generation and edit requests. The example below uses Chat Completions:

Bash
curl "https://apis.opengateway.ai/v1/chat/completions" \
  -H "Authorization: Bearer $OPENGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "deepseek/deepseek-v4.1-flash-ultrafast",
  "messages": [{"role": "user", "content": "Summarize this note."}],
  "extra": {
    "fallbacks": ["openai/gpt-5-mini", "anthropic/claude-sonnet-4-6"]
  }
}
  '

The router considers provider and region routes for the requested model first, then the fallback model IDs in the order you supplied. Provider and region ordering within a model is handled by OpenGateway's routing rules.

How the router decides to continue#

Fallbacks do not retry every error. OpenGateway classifies a failed attempt and uses that classification to decide whether to try another provider target, region, or model:

  • Authentication, permission, insufficient-balance, and rate-limit failures can move to another target in the same region; if none is available, routing continues to the next route.
  • Unavailable and timeout failures continue to another region. For an unknown or unclassified upstream error, transport failures and HTTP 404, 408, and 5xx statuses advance to another region; HTTP 401, 402, 403, and 429 advance to another target when one is available. Other unclassified statuses stop routing.
  • Request and output errors such as BAD_REQUEST, CONTENT_FILTER, and IMAGE_GENERATION_USER_ERROR stop routing. A request-side MODEL_NOT_FOUND also stops; a provider-reported model-not-found can advance to another region. A normal request error such as HTTP 400 is returned rather than retried.

If calls were made and all attempts fail, OpenGateway returns the last failure. If all candidates are rejected before an upstream call, it returns the first rejection.

Fallbacks while streaming#

For a streaming request, OpenGateway can move to another route only before it sends the first frame. After a frame is sent, it does not switch providers or restart the response. Treat an interrupted stream as incomplete. See Streaming for client-side stream handling.

Inspect attempts in Logs#

To include route details in a supported response, request extra.debug with the routing category; see Debug mode. The console's Logs table has a Job ID / Attempt column. Each recorded upstream call has the request's Job ID and its attempt index, so you can inspect the model and status for each call. See Usage and logs for more about the Logs view.

Fallbacks — OpenGateway