Model routing and selection
Section ID: Guide/jf65733bjj#overview
Explicit model IDs must pass platform validation. Metadata filters narrow eligible candidates, while provider availability and run outcomes determine whether generation succeeds.
Model selection failures
Section ID: Guide/jf65733bjj#errors-error-payload
First, distinguish an ID rejected by policy. If the send explicitly names invalid/model-xyz, the gateway refuses it with HTTP 403 and a message carrying model_access/MODEL_NOT_ALLOWED and the disallowed ID. Both send-message and send-message-sync perform this check before dispatching to the conversation. Correct every disallowed ID in the supplied primary/fallback list; adding an allowed fallback does not rescue the request.
Then distinguish a metadata-filter rejection. An allowed ID can still be absent from the resolved catalog or fail the required capability/price filter. When resolution succeeds but returns no eligible candidates, conversation preparation reports MODEL_FILTERED_OUT.
Note: A later generation failure needs different recovery
If metadata resolution itself fails, preparation can continue without that validation and leave checking to the provider path. A later selection failure can use
ERROR_CODE_MODEL_INVALIDwith reasonALL_MODELS_FILTEREDand per-model reasons in its message. Follow the accepted run’s outcome; do not treat this as the earlier gateway rejection.
Filter precedence
Section ID: Guide/jf65733bjj#filtering-how-filters-combine
| Situation | Behaviour |
|---|---|
No modelRoutingFilter set | No metadata filtering. Model-ID validation still runs. |
| Filter set, all fields zero/unset | No filtering — the same as not setting one |
Filter on overrideGenerationConfig | Applies to that message only; the next message reverts to the thread default |
A single model, no models array | The filter applies to that one model. If it fails, you get an immediate error. |
model plus models | The filter applies to the merged candidate list — model first, then models |
Allowed models
Section ID: Guide/jf65733bjj#allowed-models
Choose an exact model ID permitted for your account and deployment. Use the model catalog to compare capabilities, but confirm eligibility before selecting an entry; catalog presence and provider support do not establish permission.
A request that names a disallowed model can fail with MODEL_NOT_ALLOWED. Confirm the selected ID, provider restrictions and required capabilities before retrying. The catalog’s Undecided status means a platform selection decision has not been recorded.
Candidate resolution and fallback
Section ID: Guide/jf65733bjj#how-it-works
You can give the platform several candidate models instead of one, and constrain which of them may be used. Explicit model IDs are validated before generation starts. When candidate metadata is available, capability and price filters narrow that list during preparation. A metadata lookup failure can leave those checks to the later generation path; an accepted request is not proof that every constraint was checked.
Set models for a fallback chain, and modelRoutingFilter to require capabilities — a minimum context window, image input or a per-token price filter. Candidates that fail are dropped; generation proceeds with whatever survives. If a successful metadata lookup leaves no eligible candidates, the request is rejected before generation. Follow an accepted run to its outcome for failures discovered later.
Setting no filter is a valid choice and changes nothing about how a thread behaves.
Eligible candidates proceed to generation. Failed attempts try remaining candidates; exhaustion ends in an error. An empty eligible set also produces an error.
Available models
Section ID: Guide/jf65733bjj#configuration-available-models
The model catalog compares reported provider capabilities. It is not the deployment’s allowed-model list. Obtain the permitted exact IDs from your account or deployment operator before applying the selection rules. An Undecided catalog entry has no recorded platform selection decision.
Document ID: Guide/jf65733bjj