homelab-frontend/tasks/2.3-unknown-model-errors.md

2.3 — Unknown and missing model errors (RED)

Phase: 2 — LLM surface Stage: RED Depends on: 2.1, 2.2

• POST /v1/chat/completions with a model that is not in the configured registry returns a 4xx client error, never 5xx
• A request with no model field, a null model, or an empty-string model is the same class of client error
• A body that is not valid JSON is also a client error, distinguishable from an unknown model
• The response is RFC 9457 with Content-Type: application/problem+json
• The problem body names the rejected value and enumerates every currently configured model name, derived from the registry rather than written out by hand
• No fallback to a default model happens under any of these conditions, and no upstream is contacted
• The rejection is logged with its reason; the request body is not logged

Write the failing tests first. A silent fallback to a default model is the specific failure mode this task exists to prevent: it turns a client typo into a bill against the wrong GPU and hides the mistake from the caller.

Verify

curl -s -i localhost:8080/v1/chat/completions -H 'content-type: application/json' \
  -d '{"model":"gpt-4","messages":[]}'
# expected: 400 (or 404), content-type: application/problem+json, body lists reasoning, ornith:35b, qwen2.5:3b-instruct, and the embedding/rerank models

curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/v1/chat/completions \
  -H 'content-type: application/json' -d '{"messages":[]}'
# expected: 4xx, no upstream stub recorded any hit

curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/v1/chat/completions \
  -H 'content-type: application/json' -d 'not json'
# expected: 400, problem+json, reason distinct from unknown-model