Fallback Chains

Configure A→B→C model fallbacks so if one model fails, the gateway tries the next.

How It Works

Set the Cova-Fallbacks header with a JSON array of model names (max 5). If the primary model returns a retryable status code, the gateway tries the next model in the chain.

Retryable Status Codes

The gateway falls back on these status codes: 401, 403, 429, 500, 502, 503, 504, 529

Non-retryable codes (400, 404, 422, etc.) stop the chain and return the error.

Usage

curl

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-cova-..." \
  -H "Content-Type: application/json" \
  -H "Cova-Fallbacks: [\"gpt-4o\",\"claude-3-5-sonnet\",\"llama-3.3-70b-versatile\"]" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

TypeScript SDK

import { buildHeaders } from "@cova/gateway";

const headers = buildHeaders({
  fallbacks: ["gpt-4o", "claude-3-5-sonnet", "llama-3.3-70b-versatile"],
});

Python SDK

from cova_gateway import build_headers, CovaHeaderOptions

headers = build_headers(CovaHeaderOptions(
    fallbacks=["gpt-4o", "claude-3-5-sonnet", "llama-3.3-70b-versatile"],
))

Behavior

1. Gateway tries the primary model (from request body model field)
2. If status is retryable, gateway rewrites the model and re-resolves provider keys for the next fallback
3. Repeats until a non-retryable response or all fallbacks exhausted
4. If all fallbacks exhausted, returns the last error response

Use Case: High Availability

const headers = buildHeaders({
  fallbacks: ["gpt-4o", "claude-3-5-sonnet", "groq/llama-3.3-70b-versatile"],
});

This ensures your request succeeds even if OpenAI or Anthropic is down.