Recover when no model can serve the request

Section: DOC-MA-model-controls-errors#handle-routing-errors.

For a customer image or summary request rejected before generation, keep the input, identify the failed selection step and correct the configuration. Use this recipe for an explicit rejection; a lost send response or an already accepted run requires generation recovery instead.

The public send path checks explicit model IDs against the allowlist first. Any disallowed ID in model or models rejects the whole request, even when another supplied candidate is allowed. It is not silently removed.

After that check, conversation preparation resolves candidate metadata and applies the routing filter. A successful metadata lookup that leaves no candidates produces a different rejection. Neither rejection starts a new generation run for that request; show the error rather than waiting for its reply.

Step 1: identify a rejected request that never started

Section: DOC-MA-model-controls-errors#error-payload.

For example, suppose the candidate IDs are anthropic/claude-sonnet-5 and anthropic/claude-sonnet-4.6, and the resolved metadata for both falls below the context window your task requires. Both IDs pass the current allowlist. The following illustrates the resulting RPC error; it does not assert either model’s current catalog availability or context size:

{
  "code": "ERROR_CODE_INVALID_ARGUMENT",
  "message": "all candidate models were filtered out: [anthropic/claude-sonnet-5 anthropic/claude-sonnet-4.6]",
  "isTerminal": true,
  "details": {
    "errorInfo": {
      "reason": "MODEL_FILTERED_OUT",
      "domain": "conversation"
    }
  }
}

The two rejections do not share a payload shape. The example above is the metadata/filter rejection, which carries a structured reason. The allowlist rejection is a 403 that carries its reason in the message text instead:

{
  "code": 403,
  "message": "[403] policy denied (suspension_state=NONE): model_access/MODEL_NOT_ALLOWED: model \"openai/gpt-5\" is not allowed"
}

Match on the MODEL_NOT_ALLOWED token and the disallowed ID quoted after it. The for action \"...\" clause is present only on endpoints that name one, so do not rely on it. On the send path a request that is refused this way never starts a generation run.

Keep the returned error and candidate/filter configuration. This aggregate metadata error does not provide a per-candidate explanation of catalog absence versus filter mismatch. Inspect the available metadata and requirements before changing the request. Allowlist acceptance alone is not proof that a model is available or suitable.

Step 2: correct the selection, then send the original task

Section: DOC-MA-model-controls-errors#handling-the-response.

1. Confirm you received an explicit pre-generation rejection, rather than losing a response or observing a later run failure.
2. For MODEL_NOT_ALLOWED, correct or remove every disallowed model explicitly supplied by the request. Choose replacements from the accepted set that can serve the task.
3. For MODEL_FILTERED_OUT, inspect catalog resolution and the requested constraints. Select other permitted candidates, or relax a filter only if the task’s capability, cost and data-handling requirements still hold.
4. Send the corrected task once and follow the newly accepted run to its outcome.

Outcome	What to do
403, reason MODEL_NOT_ALLOWED	Fix the explicit disallowed ID. An allowed fallback does not bypass this check.
400, reason MODEL_FILTERED_OUT	Correct the candidate/filter combination after inspecting resolved metadata. No new generation run started for this rejection.
Accepted response with a runId	Retain the ID and follow generation outcomes. Acceptance is not a completed reply.

Once the gateway allowlist check passes, metadata resolution can omit individual candidates and continue with eligible survivors. That behavior does not apply to an explicitly disallowed ID, and an unavailable metadata check does not prove every constraint was checked.

Finished result: the customer’s input is retained while the configuration is corrected, then the new request is followed to its actual reply, failure or unresolved outcome. No duplicate send is used as a status lookup.

Document ID: DOC-MA-model-controls-errors. Section identities and revisions.