Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

gateway: a model that cannot be served when work is sent is 422 model_unavailable (#518)

github-actions[bot]df3018501ef5
diff --git a/gateway/app.py b/gateway/app.py
index 9222a138..d3fdace3 100644
--- a/gateway/app.py
+++ b/gateway/app.py
@@ -7903,7 +7903,9 @@ async def _resolve_model_policy(requested: str, hv: dict | None, backend: str, o
return default
if await _model_authorized_async(req, backend, org):
return req
- raise uhp_error(400, "model_not_available",
+ # UHP Errors §3.1: a task's model that cannot be served is `model_unavailable` (422), refused when
+ # the task is sent; `model_not_available` is the harness write's refusal of a default_model (#517).
+ raise uhp_error(422, "model_unavailable",
f"Model '{req}' is not available on the {backend} base of this instance: no connected "
f"provider serves it there. GET /v1/harnesses/{{id}}/models lists the models this "
f"harness can run.", "model")
@@ -19578,7 +19580,7 @@ async def launch_kit(kit_id: str, request: Request, body_in: KitLaunchBody | Non
if want_base not in _BASE_CATALOG:
raise uhp_error(400, "invalid_base", f"No base harness '{want_base}'.", "base")
if not await _base_serves(org, want_base, want_model):
- raise uhp_error(400, "model_unavailable",
+ raise uhp_error(422, "model_unavailable",
f"Nothing you have connected can run {want_model or 'that model'} "
f"on {want_base}.", "model")
base, model = want_base, want_model
diff --git a/gateway/tests/test_kits_workspace.py b/gateway/tests/test_kits_workspace.py
index a61fa144..edbbdbca 100644
--- a/gateway/tests/test_kits_workspace.py
+++ b/gateway/tests/test_kits_workspace.py
@@ -134,3 +134,16 @@ def test_a_relaunch_carries_the_kits_current_prompt(world, monkeypatch):
assert not third["created"] and third["harnessId"] == hid
assert store[hid]["system_prompt"] == "Build decks. The person sees only ./deck.json."
assert third["harness"]["systemPrompt"] == "Build decks. The person sees only ./deck.json."
+
+
+def test_a_launch_on_a_base_and_model_nothing_serves_is_422_model_unavailable(world, monkeypatch):
+ """UHP Errors §3.1: a model that cannot be served when the work is sent is `model_unavailable`,
+ 422, the same answer a task gets (#517). It was 400 here."""
+ async def serves_nothing(org, base, model):
+ return False
+ monkeypatch.setattr(gw, "_base_serves", serves_nothing)
+ with pytest.raises(gw.HTTPException) as e:
+ asyncio.run(gw.launch_kit("slides", _Req(), gw.KitLaunchBody(base="hermes", model="deepseek-v4-pro")))
+ assert e.value.status_code == 422
+ assert e.value.detail["code"] == "model_unavailable" and e.value.detail["param"] == "model"
+ assert "deepseek-v4-pro" in e.value.detail["message"] # the words are unchanged
diff --git a/gateway/tests/test_model_refusal.py b/gateway/tests/test_model_refusal.py
index aebded5e..8e0e69b3 100644
--- a/gateway/tests/test_model_refusal.py
+++ b/gateway/tests/test_model_refusal.py
@@ -20,8 +20,10 @@ def test_a_model_the_base_cannot_serve_is_refused_not_replaced(monkeypatch):
monkeypatch.setattr(gw, "_model_authorized_async", no)
with pytest.raises(HTTPException) as e:
asyncio.run(gw._resolve_model_policy("claude-sonnet-9", {"default_model": "claude-sonnet-5"}, "claude", "org"))
- assert e.value.status_code == 400
- assert e.value.detail["code"] == "model_not_available" and e.value.detail["param"] == "model"
+ # UHP Errors §3.1: a task's model is model_unavailable, 422; model_not_available is the harness
+ # write's code for a default_model (#517)
+ assert e.value.status_code == 422
+ assert e.value.detail["code"] == "model_unavailable" and e.value.detail["param"] == "model"
assert "claude-sonnet-9" in e.value.detail["message"] and "claude" in e.value.detail["message"]
# no request, or a bare family name, is the harness default and not a refusal
assert asyncio.run(gw._resolve_model_policy("", {"default_model": "claude-sonnet-5"}, "claude", "org")) == "claude-sonnet-5"
diff --git a/ui/src/components/ApiReference.tsx b/ui/src/components/ApiReference.tsx
index 013bf720..25a86f68 100644
--- a/ui/src/components/ApiReference.tsx
+++ b/ui/src/components/ApiReference.tsx
@@ -417,7 +417,7 @@ curl $BASE/v1/environments/$ENV/builds/1 -H "Authorization: Bearer $KEY"`} />
<Endpoint method="GET" path="/v1/harnesses/{id}/models">
<p className="hr-meta">The models this agent may run and its default. A run requesting a model
- outside this set is refused before it starts (<code>400 model_not_available</code>); nothing
+ outside this set is refused before it starts (<code>422 model_unavailable</code>); nothing
runs on a model the caller did not ask for.</p>
</Endpoint>