If your gateway advertises a model ID, clients should be able to use that exact ID on the supported request path—and rely on any capabilities the catalogue claims. A successful GET /v1/models response alone does not prove that the listed models are callable or correctly configured. Official documentation describes concrete ways discovery and execution can diverge, but does not establish how common those failures are.
What does a public model list promise?
OpenAI’s API reference describes GET /v1/models as listing currently available models and providing basic information such as owner and availability. The documented model object includes id, created, object, and owned_by, with an optional shutdown_date. The id is the identifier that can be referenced in API endpoints. OpenAI’s model-list reference therefore gives clients a reasonable basis to treat a discovered ID as an identifier they can try on the relevant API path.
As an Amazon Associate I earn from qualifying purchases.
That is a useful minimum, not a complete guarantee. Gateways may add aliases, route requests to upstream providers, and describe capabilities beyond simple model existence. Clients need to know what an ID means, which operations it supports, and how current that information is.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why is a model in /v1/models but my request says the model doesn’t exist?
A common design source of mismatch is the difference between a public alias and an upstream model name. Kong documents that a gateway can configure a client-facing alias that routes to a differently named upstream model. Its example explains that this decouples the client API from provider changes. If the public catalogue exposes one identifier but the route expects another—or if the alias is missing or stale—a request using the advertised ID can fail.
#1 Best Overall
The reverse assumption can also fail: a client may send the provider’s upstream name when the gateway requires its configured public alias. Kong specifically documents that the configured alias, rather than the upstream name, is the name the client should use in that arrangement. See Kong’s AI Models documentation for its alias and routing behavior.
Other plausible drift cases follow from keeping discovery, routing, and capability configuration separate: a stale ID remains in the list after its route changes; an alias resolves to an unexpected upstream; or a model is listed even though the capability needed for a request is not configured. These are useful cases to test, not reported incidents or evidence that any particular gateway has them.
Does an OpenAI-compatible gateway’s list guarantee that every listed model works?
No. Compatibility with an API shape does not, by itself, establish that every discovered identifier maps to a working route or supports every operation a client might attempt. LiteLLM documents that routing-group names appear in /v1/models discovery, while Kong documents alias routing and per-model capability configuration as separate concerns. A list response is evidence of what the gateway exposes; execution tests are needed to verify that the exposed names and claimed behaviors work together.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Nor should a model name be treated as a full capability description. OpenRouter’s catalogue documentation includes properties such as input and output modalities, context length, pricing, supported parameters, and provider details. These fields can affect whether a model is suitable for a client’s task. See OpenRouter’s model catalogue reference.
Rank #3
What should a useful catalogue tell clients?
Gateway designs differ, so evaluate the contract along the dimensions that affect callers rather than assuming that every catalogue has the same semantics.
| Contract dimension | What to establish |
|---|---|
| Identifier semantics | Is the listed ID an upstream name, a gateway-owned alias, or both? If it is an alias, is it intended to remain stable when the upstream changes? |
| Discovery scope | Does /v1/models include model names, routing groups, or both? Is the response scoped to the caller’s authorization context? LiteLLM documents routing-group names in discovery; verify access behavior in the deployment you use. LiteLLM’s router documentation |
| Capability declaration | Does each entry identify supported operations or modalities, and do those claims match the gateway’s configured routes? Kong documents per-model capability configuration; OpenRouter documents richer catalogue metadata. |
| Metadata freshness | Are context length, supported parameters, pricing, provider, and retirement information exposed where relevant, and kept up to date? OpenAI’s model object also documents an optional shutdown date. |
| Failure visibility | Can a caller distinguish an invalid public ID or unsupported operation from an upstream failure? Kong documents an alias mismatch path, but the cited sources do not provide a cross-vendor comparison of error clarity. |
How to test the IDs your gateway advertises
Run the checks with a staging key or another low-impact environment. Use the same base URL and authorization context as the intended client; otherwise, the test may exercise a different catalogue or route.
- Capture discovery. Request
GET /v1/modelsthrough the client-facing base URL using the intended authorization context. Save the response as a fixture so you can compare later changes. - Exercise every advertised ID. For each listed
idor alias, send a minimal request to the relevant supported endpoint. Record the HTTP status, any returned model name, and whether the request reached the intended route. - Verify the public name against routing. Compare each public identifier with the gateway’s alias rules and upstream targets. Test the exact public alias; do not substitute an upstream provider’s model name unless the gateway contract says to use it. Kong documents a setup in which the alias is the required client-facing name.
- Test each claimed capability separately. Compare catalogue claims with configured capabilities, then exercise each exposed operation—such as chat completion, embeddings, or image generation—rather than assuming success on one path proves the others work.
- Check for silent drift. Include stale IDs, aliases resolving to an unexpected upstream, entries without the needed capability configuration, and catalogue fields that disappear or change type in your test cases.
- Make the contract observable. As an engineering practice, alert on catalogue-to-route mismatches and rerun the checks when model or routing configuration changes. This is a recommendation, not a vendor requirement established by the cited documentation.
What the evidence does—and doesn’t—show
The documented mechanisms make catalogue-to-execution mismatches a real design risk: aliases can differ from upstream names, routing groups can appear in discovery, and capabilities can be configured separately. The cited official documentation does not establish what proportion of gateways violate their advertised behavior, so it cannot support a claim that “most” do. Treat that wording as a warning, not a measured prevalence statistic.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
