Build model and provider fallback with CometAPI

Build two fallback layers for text requests. Keep CometAPI as the primary route. First, change the model ID inside CometAPI. If those routes fail and official fallback is enabled, call the matching official provider.

Model fallback inside CometAPI

Keep the same CometAPI API key and base URL. Try a compatible secondary model ID after the primary model fails.

Official-provider fallback

Use a separate OpenAI or Anthropic client, API key, model ID, account, and billing configuration.

The recommended order is CometAPI primary model → CometAPI fallback model → matching official provider.

Decide when to fallback

Use a narrow error policy so that fallback does not hide request problems:

Failure	Use the next route?
Connection error, timeout, `408`, `429`, or temporary `5xx`	Yes. Try the next configured route.
Verified model-unavailable, balance, or quota signal	Add that exact signal to the classifier before you use it
Invalid request, invalid API key, or unsupported parameter	No. Fix the request or configuration.

The examples below use ENABLE_OFFICIAL_FALLBACK as the explicit switch. If you also fallback on a model or account limit, add only its verified error signal to your application’s error classifier. Install openai and anthropic for Python, or install openai and @anthropic-ai/sdk for Node.js. Then configure these environment variables:

OpenAI route: COMETAPI_KEY, COMETAPI_OPENAI_PRIMARY_MODEL, COMETAPI_OPENAI_FALLBACK_MODEL, OPENAI_API_KEY, and OPENAI_OFFICIAL_MODEL
Claude route: COMETAPI_KEY, COMETAPI_CLAUDE_PRIMARY_MODEL, COMETAPI_CLAUDE_FALLBACK_MODEL, ANTHROPIC_API_KEY, and ANTHROPIC_OFFICIAL_MODEL
Shared controls: ENABLE_OFFICIAL_FALLBACK and ROUTE_TIMEOUT_MS

ENABLE_OFFICIAL_FALLBACK defaults to false. Set it to true only when the official-provider account is ready. ROUTE_TIMEOUT_MS is the timeout for each attempt and defaults to 30 seconds. Set it from your application’s latency budget; total fallback time can include all three attempts. Choose fallback models that support the same request format and the capabilities that your application requires. Test every route before you depend on it.

Official-provider requests use a separate account and billing configuration. Configure provider budgets and alerts before you enable this route. Record the official fallback rate so that you can investigate sustained usage.

Implement the fallback chain

Choose the tab that matches the request format that your application uses. Configure separate model IDs for the CometAPI and official-provider routes.

OpenAI models
Claude models

Use Chat Completions for both CometAPI and the OpenAI official API. The request shape stays the same, but each route has its own client, API key, and model ID.

import os

from openai import APIError, OpenAI

official_fallback_enabled = (
    os.getenv("ENABLE_OFFICIAL_FALLBACK", "false").lower() == "true"
)
route_timeout = int(os.getenv("ROUTE_TIMEOUT_MS", "30000")) / 1000

cometapi = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
    max_retries=0,
    timeout=route_timeout,
)
routes = [
    (
        "cometapi-primary",
        cometapi,
        os.environ["COMETAPI_OPENAI_PRIMARY_MODEL"],
    ),
    (
        "cometapi-fallback",
        cometapi,
        os.environ["COMETAPI_OPENAI_FALLBACK_MODEL"],
    ),
]
if official_fallback_enabled:
    routes.append(
        (
            "openai-official",
            OpenAI(
                api_key=os.environ["OPENAI_API_KEY"],
                base_url="https://api.openai.com/v1",
                max_retries=0,
                timeout=route_timeout,
            ),
            os.environ["OPENAI_OFFICIAL_MODEL"],
        )
    )


def should_fallback(error: APIError) -> bool:
    status = getattr(error, "status_code", None)
    code = getattr(error, "code", None)
    return (
        status is None
        or status in {408, 429}
        or (
            status >= 500
            and code not in {"invalid_request", "invalid_request_error"}
        )
    )


def complete(messages: list[dict]) -> dict:
    for index, (route, client, model) in enumerate(routes):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
            )
            return {
                "text": response.choices[0].message.content,
                "route": route,
                "model": model,
            }
        except APIError as error:
            if index == len(routes) - 1 or not should_fallback(error):
                raise

    raise RuntimeError("No fallback route completed.")


result = complete(
    [{"role": "user", "content": "Summarize CometAPI in one sentence."}]
)
print(result)

import OpenAI from "openai";

function requiredEnv(name) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is required.`);
  }
  return value;
}

const officialFallbackEnabled =
  process.env.ENABLE_OFFICIAL_FALLBACK === "true";
const routeTimeout = Number(process.env.ROUTE_TIMEOUT_MS ?? 30000);

const cometapi = new OpenAI({
  apiKey: requiredEnv("COMETAPI_KEY"),
  baseURL: "https://api.cometapi.com/v1",
  maxRetries: 0,
  timeout: routeTimeout,
});
const routes = [
  {
    route: "cometapi-primary",
    client: cometapi,
    model: requiredEnv("COMETAPI_OPENAI_PRIMARY_MODEL"),
  },
  {
    route: "cometapi-fallback",
    client: cometapi,
    model: requiredEnv("COMETAPI_OPENAI_FALLBACK_MODEL"),
  },
];
if (officialFallbackEnabled) {
  routes.push({
    route: "openai-official",
    client: new OpenAI({
      apiKey: requiredEnv("OPENAI_API_KEY"),
      baseURL: "https://api.openai.com/v1",
      maxRetries: 0,
      timeout: routeTimeout,
    }),
    model: requiredEnv("OPENAI_OFFICIAL_MODEL"),
  });
}

function shouldFallback(error) {
  if (!(error instanceof OpenAI.APIError)) {
    throw error;
  }

  return (
    error.status === undefined ||
    error.status === 408 ||
    error.status === 429 ||
    (error.status >= 500 &&
      !["invalid_request", "invalid_request_error"].includes(error.code))
  );
}

async function complete(messages) {
  for (const [index, { route, client, model }] of routes.entries()) {
    try {
      const response = await client.chat.completions.create({
        model,
        messages,
      });
      return {
        text: response.choices[0].message.content,
        route,
        model,
      };
    } catch (error) {
      if (index === routes.length - 1 || !shouldFallback(error)) {
        throw error;
      }
    }
  }

  throw new Error("No fallback route completed.");
}

const result = await complete([
  { role: "user", content: "Summarize CometAPI in one sentence." },
]);
console.log(result);

If your application uses the Responses API, keep the same dual-client routing pattern and adapt the request and response fields. See the official Chat Completions reference.

Use the Anthropic Messages request format for both CometAPI and the Anthropic official API. This avoids converting between OpenAI-compatible messages and Anthropic content blocks during fallback.

import os

import anthropic

official_fallback_enabled = (
    os.getenv("ENABLE_OFFICIAL_FALLBACK", "false").lower() == "true"
)
route_timeout = int(os.getenv("ROUTE_TIMEOUT_MS", "30000")) / 1000

cometapi = anthropic.Anthropic(
    api_key=os.environ["COMETAPI_KEY"],
    auth_token=None,
    base_url="https://api.cometapi.com",
    max_retries=0,
    timeout=route_timeout,
)
routes = [
    (
        "cometapi-primary",
        cometapi,
        os.environ["COMETAPI_CLAUDE_PRIMARY_MODEL"],
    ),
    (
        "cometapi-fallback",
        cometapi,
        os.environ["COMETAPI_CLAUDE_FALLBACK_MODEL"],
    ),
]
if official_fallback_enabled:
    routes.append(
        (
            "anthropic-official",
            anthropic.Anthropic(
                api_key=os.environ["ANTHROPIC_API_KEY"],
                auth_token=None,
                base_url="https://api.anthropic.com",
                max_retries=0,
                timeout=route_timeout,
            ),
            os.environ["ANTHROPIC_OFFICIAL_MODEL"],
        )
    )


def should_fallback(error: anthropic.APIError) -> bool:
    status = getattr(error, "status_code", None)
    body = getattr(error, "body", {}) or {}
    details = body.get("error", {}) if isinstance(body, dict) else {}
    code = details.get("code") or details.get("type")
    return (
        status is None
        or status in {408, 429}
        or (
            status >= 500
            and code not in {"invalid_request", "invalid_request_error"}
        )
    )


def text_from_message(message) -> str:
    return "".join(
        block.text for block in message.content if block.type == "text"
    )


def complete(messages: list[dict]) -> dict:
    for index, (route, client, model) in enumerate(routes):
        try:
            response = client.messages.create(
                model=model,
                max_tokens=512,
                messages=messages,
            )
            return {
                "text": text_from_message(response),
                "route": route,
                "model": model,
            }
        except anthropic.APIError as error:
            if index == len(routes) - 1 or not should_fallback(error):
                raise

    raise RuntimeError("No fallback route completed.")


result = complete(
    [{"role": "user", "content": "Summarize CometAPI in one sentence."}]
)
print(result)

import Anthropic from "@anthropic-ai/sdk";

function requiredEnv(name) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is required.`);
  }
  return value;
}

const officialFallbackEnabled =
  process.env.ENABLE_OFFICIAL_FALLBACK === "true";
const routeTimeout = Number(process.env.ROUTE_TIMEOUT_MS ?? 30000);

const cometapi = new Anthropic({
  apiKey: requiredEnv("COMETAPI_KEY"),
  authToken: null,
  baseURL: "https://api.cometapi.com",
  maxRetries: 0,
  timeout: routeTimeout,
});
const routes = [
  {
    route: "cometapi-primary",
    client: cometapi,
    model: requiredEnv("COMETAPI_CLAUDE_PRIMARY_MODEL"),
  },
  {
    route: "cometapi-fallback",
    client: cometapi,
    model: requiredEnv("COMETAPI_CLAUDE_FALLBACK_MODEL"),
  },
];
if (officialFallbackEnabled) {
  routes.push({
    route: "anthropic-official",
    client: new Anthropic({
      apiKey: requiredEnv("ANTHROPIC_API_KEY"),
      authToken: null,
      baseURL: "https://api.anthropic.com",
      maxRetries: 0,
      timeout: routeTimeout,
    }),
    model: requiredEnv("ANTHROPIC_OFFICIAL_MODEL"),
  });
}

function shouldFallback(error) {
  if (!(error instanceof Anthropic.APIError)) {
    throw error;
  }

  const details = error.error?.error ?? error.error ?? {};
  const code = details.code ?? details.type ?? error.type;
  return (
    error.status === undefined ||
    error.status === 408 ||
    error.status === 429 ||
    (error.status >= 500 &&
      !["invalid_request", "invalid_request_error"].includes(code))
  );
}

function textFromMessage(message) {
  return message.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("");
}

async function complete(messages) {
  for (const [index, { route, client, model }] of routes.entries()) {
    try {
      const response = await client.messages.create({
        model,
        max_tokens: 512,
        messages,
      });
      return {
        text: textFromMessage(response),
        route,
        model,
      };
    } catch (error) {
      if (index === routes.length - 1 || !shouldFallback(error)) {
        throw error;
      }
    }
  }

  throw new Error("No fallback route completed.");
}

const result = await complete([
  { role: "user", content: "Summarize CometAPI in one sentence." },
]);
console.log(result);

For the complete request and response format, see the official Anthropic Messages reference.

Switch between model families

GPT and Claude can fallback to each other when your application converts both requests to shared fields, normalizes both responses, and verifies the required capabilities on every route. A model ID change alone is not enough when request or response shapes differ.

Start here

Model API quickstarts

Core API guides

Libraries

Errors

Pricing and billing

Support

Build model and provider fallback with CometAPI

Model fallback inside CometAPI

Official-provider fallback

Decide when to fallback

Implement the fallback chain

Switch between model families

Model fallback inside CometAPI

Official-provider fallback

​Decide when to fallback

​Implement the fallback chain

​Switch between model families

​Related links

Decide when to fallback

Implement the fallback chain

Switch between model families

Related links