Refused & Empty Responses

Sometimes no model behind your alias can produce a usable answer at the completion budget you asked for. SpiderGate now works that out before it contacts a provider, so it either moves your request to a model that can serve it or refuses with a 422 that costs you nothing. This page explains what you will see and what to change.

Who this is for: anyone whose request came back with an empty completion, or who has started seeing no_qualifying_model where a 200 used to arrive.

What you'll learn: why this happens, how to read the refusal, and what to change so the request is served.

Before you begin

You need a gateway token and a request that is failing or returning empty content. Nothing has to be enabled: this check is on for every chat request.

Why a request used to come back empty

Some models stop producing output well below their advertised limits. Ask one for a 16-token completion and it can return a well-formed response with an empty content string. The HTTP status was 200, the usage was billed, and nothing in the response distinguished that from a real answer.

What happens now

Before your request is dispatched, SpiderGate checks each candidate model against what it has actually been measured doing at that completion budget.

::table
Outcome | What you see
A candidate is disqualified but another can serve | `200`, served by the other model. No change to your call
Every candidate is disqualified | `422` with `no_qualifying_model`, and no tokens spent
Nothing is disqualified | `200`, exactly as before

Rerouting narrows the pool for that one request. Your alias, its fallback chain and its load balancing all behave as they did before.

Reading the refusal

The 422 body names every candidate it considered and the verdict that ruled each one out:

{
  "error": {
    "type": "invalid_request_error",
    "code": "no_qualifying_model",
    "message": "No model behind 'MiniMax-M2.5' can serve a completion budget of 16 tokens. Every candidate is measured to fail at this budget — raise max_tokens or request a different model."
  },
  "spidergate_error": {
    "requested_model": "MiniMax-M2.5",
    "completion_budget": 16,
    "candidates": [
      { "model": "MiniMax-M2.5", "provider": "openai", "verdict": "known_empty_at_budget" }
    ]
  }
}

known_empty_at_budget means that model has been measured returning an empty completion at this budget. exceeds_tier_ceiling means your budget is above the output ceiling measured for that model on its tier.

How to get the request served

Raise max_tokens. This is the usual fix. The refusal is tied to the budget you asked for, so the same model and alias will often serve the same prompt at a larger budget.

Or ask for a different model or alias. Pick one from Models & Direct Routing, or use a task alias with more than one model behind it — see Task Aliases.

Do not retry the same request. A 422 here carries no Retry-After and is not a transient failure. The same request fails the same way every time, so a retry loop will spin without ever succeeding.

Check it worked

Send the request again with the larger budget and confirm you get a 200 with a non-empty content. To see which model actually served it, read the x-served-model-catalog-id response header, or open Traces in the dashboard at /dashboard/gate/traces and inspect the request — a rerouted request shows the model that served it rather than the one you asked for.

Telling your agent

If you drive SpiderGate from an agent, give it this rule directly:

If SpiderGate returns 422 with code no_qualifying_model, do not retry the request.
Raise max_tokens and send it again, or choose a different model or alias.

The gateway skill package carries this and the rest of the gateway contract:

npx @opvs-ai/skills install @spideriq/gateway-skills

Troubleshooting

You raised max_tokens and still get a 422. Every model behind that alias is disqualified at the new budget too. Read the candidates array — it lists each one and its verdict. Choose a different alias.

You pinned one concrete model. A single model gives the gate nothing to reroute to, so a disqualification becomes a refusal immediately. Use a task alias instead if you want the reroute.

You get an empty 200 rather than a 422. The gate refuses on measurements it already holds. A model it has not yet measured at your budget is allowed through, so an empty response is still possible on a model with no measurement history.

Next steps

1. Understand the endpoint — Chat Completions.

2. See every status code — Errors.

3. Inspect a request end to end — Traces.