# OmniRoute Model Deprecation Detection and Migration Workflow

> Learn how OmniRoute automatically detects deprecated models, migrates them to successors, or returns errors. Discover the seamless model deprecation workflow.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: workflow
- Published: 2026-07-01

---

**OmniRoute's Open-SSE service layer automatically detects deprecated model IDs by checking the provider catalog against incoming requests, silently rewriting the model field to a configured successor, or returning a 4xx error when no migration path is defined.**

The `diegosouzapw/OmniRoute` repository implements a robust **model deprecation detection and migration** workflow that shields API clients from breaking changes in the rapidly evolving LLM provider landscape. When a request hits an endpoint like `/api/v1/chat/completions`, the platform intercepts the call to validate model availability and execute seamless failover logic without client-side modifications.

## Core Architecture of the Deprecation Service

### The Model Deprecation Service Layer

The central logic resides in [`open-sse/services/modelDeprecation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/modelDeprecation.ts). This module exports the `handle()` method that receives the parsed request object immediately after Zod schema validation. According to the OmniRoute source code, this service acts as a gatekeeper between the route handler and the execution pipeline, ensuring that obsolete model IDs never reach the translation layer.

### Provider Catalog Metadata

Deprecation metadata is stored in the provider catalog TypeScript definitions, such as [`src/shared/constants/providers/apikey/frontier-labs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/frontier-labs.ts). Each model entry optionally includes:

- **`deprecationReason?: string`** – A human-readable explanation indicating why the model is obsolete
- **`successorModelId?: string`** – The target model identifier for automatic request migration

## Step-by-Step Migration Flow

The **model deprecation detection and migration** process follows this execution path:

1. **Request enters route** – Client calls `POST /api/v1/chat/completions`

2. **Body validation** – Zod schema validates the request shape and extracts the `model` field

3. **Model deprecation check** – `modelDeprecation.handle()` receives the parsed request object

4. **Catalog lookup** – The service fetches the provider's model definition from the in-memory catalog (`src/shared/constants/providers/*`)

5. **Deprecation detection** – The service checks if `deprecationReason` exists on the catalog entry

6. **Successor resolution** – If `successorModelId` is configured, the service rewrites `request.body.model` to the new ID

7. **Logging** – A structured log entry records the original and new model IDs via the omni-route logger

8. **Forwarding** – The mutated request continues through [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) for translation and execution against the live provider

9. **Response handling** – The backend returns the response using the successor model while preserving the original model name in metadata for backward compatibility

## Implementing Model Deprecation

To deprecate a model in OmniRoute, edit the relevant provider configuration file (e.g., [`src/shared/constants/providers/apikey/anthropic.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/anthropic.ts)):

```typescript
{
  id: "claude-2",
  name: "Claude 2",
  deprecationReason: "Replaced by claude-3.5-sonnet",
  successorModelId: "claude-3.5-sonnet"
}

```

Once the catalog is updated, the `modelDeprecation` service automatically picks up the changes without requiring modifications to the core service logic.

## Error Handling for Retired Models

When a model has a `deprecationReason` but lacks a `successorModelId`, the service throws a `DeprecationError`. The route handler catches this exception and converts it into a `4xx` HTTP response (typically `410 Gone`) with a clear migration message:

```http
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": {
    "code": "model_deprecated",
    "message": "Model `old-model-x` is deprecated and no longer available. Please update your provider configuration."
  }
}

```

This behavior forces explicit client updates when no automatic migration path exists, preventing silent failures or unintended model substitutions.

## Real-World Migration Example

Consider a client requesting the deprecated `gpt-3.5-turbo` model:

```typescript
// Client request
POST /api/v1/chat/completions
{
  "model": "gpt-3.5-turbo",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

```

The provider catalog entry defines:

```typescript
deprecationReason: "Legacy model, superseded by gpt-4o-mini",
successorModelId: "gpt-4o-mini"

```

Internally, the service executes:

```typescript
request.body.model = "gpt-4o-mini";

```

The request proceeds to the OpenAI-compatible executor, which calls the live `gpt-4o-mini` endpoint. The client receives the response with backward compatibility preserved—the original model name remains visible in response metadata while the backend communicates with the modern model.

## Summary

- OmniRoute's **model deprecation detection and migration** logic is centralized in [`open-sse/services/modelDeprecation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/modelDeprecation.ts)
- Provider catalogs define deprecation status via `deprecationReason` and `successorModelId` fields in files like [`src/shared/constants/providers/apikey/frontier-labs.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/apikey/frontier-labs.ts)
- The `modelDeprecation.handle()` method silently rewrites legacy model IDs to their successors before execution in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)
- Requests to retired models without successors receive `410 Gone` errors with explicit migration instructions
- The architecture maintains backward compatibility by preserving original model names in response metadata while routing traffic to current model versions

## Frequently Asked Questions

### What happens if a client requests a deprecated model that has no successor defined?

The service throws a `DeprecationError` that the route handler converts into a `4xx` HTTP response, typically `410 Gone`. This forces the client to update their integration rather than silently failing or routing to an unintended alternative model.

### Where is the deprecation metadata configured in OmniRoute?

Deprecation metadata lives in the provider catalog TypeScript files under `src/shared/constants/providers/**/*.ts`, where each model entry can specify `deprecationReason` and `successorModelId` properties to trigger automatic migration.

### How does OmniRoute maintain backward compatibility during model migration?

While the backend executes requests against the successor model, the response metadata retains the original model name requested by the client. This ensures that existing integrations continue to function without breaking changes to response parsing logic.

### Which service handles the actual model ID rewriting?

The `modelDeprecation` service in [`open-sse/services/modelDeprecation.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/modelDeprecation.ts) contains the `handle()` method that performs the detection, logging, and silent rewriting of the model field before the request reaches the translation and execution pipeline.