test: check request errors and stop asserting PathRewrite on /v1/models

/v1/models is served from config by ServeHTTP (task 2.5) so it never reaches
routing; the rewrite test now uses a non-reserved path.

API.md

@@ -0,0 +1,934 @@
+# API Gateway Documentation
+
+## Overview
+
+The homelab-frontend gateway is a production-ready reverse proxy for LLM model inference. It routes requests to multiple model upstreams based on configuration, with support for streaming, tool calling, and multiple API formats.
+
+**Base URL**: `https://api.riotpiao.com`
+
+**Deployment**: Client → nginx ingress → gateway → model upstreams
+
+---
+
+## Table of Contents
+
+1. [Health Endpoints](#health-endpoints)
+2. [GET /v1/models](#get-v1models) - List available models
+3. [POST /v1/chat/completions](#post-v1chat-completions) - Chat with LLM
+4. [POST /v1/embeddings](#post-v1embeddings) - Generate embeddings
+5. [POST /v1/rerank](#post-v1rerank) - Rerank documents
+6. [Error Handling](#error-handling)
+7. [Examples](#examples)
+
+---
+
+## Health Endpoints
+
+### GET /healthz
+
+Always returns 200 (liveness probe).
+
+**Response**: 
+```json
+{"status":"alive"}
+```
+
+**Status Code**: 200
+
+---
+
+### GET /readyz
+
+Returns 200 when the gateway is ready (config loaded, upstreams available).
+
+**Response**:
+```json
+{"status":"ready"}
+```
+
+**Status Code**: 200 (ready) or 503 (not ready)
+
+---
+
+## GET /v1/models
+
+List all configured models available for dispatch.
+
+**Method**: GET
+
+**Path**: `/v1/models`
+
+**Authentication**: None required
+
+**Query Parameters**: None
+
+**Request Headers**:
+```
+Accept: application/json
+```
+
+**Response Headers**:
+```
+Content-Type: application/json
+```
+
+**Response Schema**:
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "model-name",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    }
+  ]
+}
+```
+
+**Status Codes**:
+- `200` - OK
+
+**Example**:
+
+```bash
+curl -s https://api.riotpiao.com/v1/models | jq .
+```
+
+**Response Example**:
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "reasoning",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    },
+    {
+      "id": "ornith:35b",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    },
+    {
+      "id": "qwen2.5:3b-instruct",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    },
+    {
+      "id": "nomic-ai/nomic-embed-text-v2-moe",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    },
+    {
+      "id": "BAAI/bge-reranker-base",
+      "object": "model",
+      "owned_by": "api.riotpiao.com",
+      "created": 1700000000
+    }
+  ]
+}
+```
+
+---
+
+## POST /v1/chat/completions
+
+Chat with an LLM model. Routes to upstream based on the `model` field in the request body.
+
+**Method**: POST
+
+**Path**: `/v1/chat/completions`
+
+**Authentication**: None required (future: Bearer token)
+
+**Request Headers**:
+```
+Content-Type: application/json
+```
+
+**Request Body Schema**:
+```json
+{
+  "model": "string (required)",
+  "messages": [
+    {
+      "role": "string (user|assistant|system)",
+      "content": "string|array (required)",
+      "tool_calls": "array (optional, from assistant)"
+    }
+  ],
+  "temperature": "number (optional, 0-2)",
+  "top_p": "number (optional, 0-1)",
+  "max_tokens": "integer (optional)",
+  "stream": "boolean (optional, default: false)",
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "string",
+        "description": "string",
+        "parameters": "object"
+      }
+    }
+  ]
+}
+```
+
+**Response Schema** (non-streaming):
+```json
+{
+  "id": "string",
+  "object": "chat.completion",
+  "created": "integer",
+  "model": "string",
+  "choices": [
+    {
+      "index": "integer",
+      "message": {
+        "role": "assistant",
+        "content": "string|null",
+        "tool_calls": [
+          {
+            "id": "string",
+            "type": "function",
+            "function": {
+              "name": "string",
+              "arguments": "string (JSON)"
+            }
+          }
+        ]
+      },
+      "finish_reason": "stop|tool_calls|length"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": "integer",
+    "completion_tokens": "integer",
+    "total_tokens": "integer"
+  }
+}
+```
+
+**Response Schema** (streaming):
+```
+data: {"id":"...", "object":"chat.completion.chunk", "choices":[...]}
+data: {"id":"...", "object":"chat.completion.chunk", "choices":[...]}
+...
+data: [DONE]
+```
+
+**Status Codes**:
+- `200` - OK
+- `400` - Bad request (missing/invalid model, invalid JSON, etc.)
+- `500` - Internal server error (upstream issue)
+
+**Supported Models**:
+- `reasoning` - Reasoning model
+- `ornith:35b` - Ornith 35B model
+- `qwen2.5:3b-instruct` - Qwen 2.5 3B model
+
+**Examples**:
+
+### Basic Chat
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {
+        "role": "user",
+        "content": "What is the capital of France?"
+      }
+    ]
+  }'
+```
+
+### Chat with Tool Calling
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {
+        "role": "user",
+        "content": "What is the weather in San Francisco?"
+      }
+    ],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "get_weather",
+          "description": "Get the weather for a location",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "location": {
+                "type": "string",
+                "description": "City name"
+              },
+              "unit": {
+                "type": "string",
+                "enum": ["celsius", "fahrenheit"]
+              }
+            },
+            "required": ["location"]
+          }
+        }
+      }
+    ]
+  }'
+```
+
+### Streaming Chat
+
+```bash
+curl -N -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Count from 1 to 3"
+      }
+    ],
+    "stream": true
+  }'
+```
+
+### Multi-turn Conversation with Tool Results
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {
+        "role": "user",
+        "content": "What is the weather?"
+      },
+      {
+        "role": "assistant",
+        "tool_calls": [
+          {
+            "id": "call_123",
+            "type": "function",
+            "function": {
+              "name": "get_weather",
+              "arguments": "{\"location\": \"San Francisco\"}"
+            }
+          }
+        ]
+      },
+      {
+        "role": "tool",
+        "content": "{\"temperature\": 22, \"condition\": \"sunny\"}"
+      }
+    ],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "get_weather",
+          "description": "Get weather",
+          "parameters": {}
+        }
+      }
+    ]
+  }'
+```
+
+---
+
+## POST /v1/embeddings
+
+Generate embeddings for text input.
+
+**Method**: POST
+
+**Path**: `/v1/embeddings`
+
+**Authentication**: None required
+
+**Request Headers**:
+```
+Content-Type: application/json
+```
+
+**Request Body Schema**:
+```json
+{
+  "model": "string (required)",
+  "input": "string | array of strings (required)",
+  "encoding_format": "float | base64 (optional)"
+}
+```
+
+**Response Schema**:
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "embedding": [0.1, 0.2, ...],
+      "index": "integer"
+    }
+  ],
+  "model": "string",
+  "usage": {
+    "prompt_tokens": "integer",
+    "total_tokens": "integer"
+  }
+}
+```
+
+**Status Codes**:
+- `200` - OK
+- `400` - Bad request (missing/invalid model, etc.)
+- `500` - Internal server error
+
+**Supported Models**:
+- `nomic-ai/nomic-embed-text-v2-moe` - Embedding model
+
+**Examples**:
+
+### Single Input
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/embeddings \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "nomic-ai/nomic-embed-text-v2-moe",
+    "input": "The quick brown fox"
+  }'
+```
+
+### Multiple Inputs
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/embeddings \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "nomic-ai/nomic-embed-text-v2-moe",
+    "input": [
+      "Document 1 text",
+      "Document 2 text",
+      "Document 3 text"
+    ]
+  }'
+```
+
+---
+
+## POST /v1/rerank
+
+Rerank documents based on relevance to a query.
+
+**Method**: POST
+
+**Path**: `/v1/rerank`
+
+**Authentication**: None required
+
+**Request Headers**:
+```
+Content-Type: application/json
+```
+
+**Request Body Schema**:
+```json
+{
+  "model": "string (required)",
+  "query": "string (required)",
+  "texts": ["string"],
+  "top_k": "integer (optional)",
+  "return_documents": "boolean (optional)"
+}
+```
+
+**Response Schema**:
+```json
+{
+  "results": [
+    {
+      "index": "integer",
+      "score": "float (0-1)",
+      "text": "string (optional)"
+    }
+  ]
+}
+```
+
+**Status Codes**:
+- `200` - OK
+- `400` - Bad request (missing/invalid model, etc.)
+- `500` - Internal server error
+
+**Supported Models**:
+- `BAAI/bge-reranker-base` - BGE reranker model
+
+**Note**: The gateway rewrites the path from `/v1/rerank` to `/rerank` on the upstream.
+
+**Examples**:
+
+### Basic Reranking
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/rerank \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "BAAI/bge-reranker-base",
+    "query": "What is machine learning?",
+    "texts": [
+      "Machine learning is a type of artificial intelligence",
+      "Dogs are animals",
+      "Deep learning is a subset of machine learning",
+      "Python is a programming language"
+    ]
+  }'
+```
+
+### With Top-K Parameter
+
+```bash
+curl -X POST https://api.riotpiao.com/v1/rerank \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "BAAI/bge-reranker-base",
+    "query": "best practices",
+    "texts": [
+      "Follow code style guidelines",
+      "Write unit tests",
+      "Use meaningful variable names",
+      "Eat healthy food"
+    ],
+    "top_k": 2
+  }'
+```
+
+---
+
+## Error Handling
+
+### Error Response Format
+
+The gateway returns RFC 9457 Problem Details for client errors (4xx):
+
+```json
+{
+  "type": "https://api.example.com/problems/error-type",
+  "title": "Human-readable error title",
+  "status": 400,
+  "detail": "Detailed explanation of what went wrong",
+  "valid_models": ["model1", "model2"] // Only for model-related errors
+}
+```
+
+### Error Types
+
+#### Unknown Model Error
+
+**Status**: `400 Bad Request`
+
+**Trigger**: Model name not in registry
+
+**Response**:
+```json
+{
+  "type": "https://api.example.com/problems/unknown-model",
+  "title": "Unknown Model",
+  "status": 400,
+  "detail": "Model \"gpt-4\" is not available. See valid_models for available options.",
+  "valid_models": ["reasoning", "ornith:35b", "qwen2.5:3b-instruct", "nomic-ai/nomic-embed-text-v2-moe", "BAAI/bge-reranker-base"]
+}
+```
+
+**Example**:
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gpt-4","messages":[]}'
+```
+
+#### Missing Model Field
+
+**Status**: `400 Bad Request`
+
+**Trigger**: No `model` field in request body
+
+**Response**:
+```json
+{
+  "type": "https://api.example.com/problems/missing-model",
+  "title": "Missing Model",
+  "status": 400,
+  "detail": "The 'model' field is required and must be a non-empty string",
+  "valid_models": [...]
+}
+```
+
+**Example**:
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"messages":[]}'
+```
+
+#### Invalid JSON
+
+**Status**: `400 Bad Request`
+
+**Trigger**: Request body is not valid JSON
+
+**Response**:
+```json
+{
+  "type": "https://api.example.com/problems/invalid-request-body",
+  "title": "Invalid Request Body",
+  "status": 400,
+  "detail": "request body is not valid JSON"
+}
+```
+
+**Example**:
+```bash
+curl -X POST https://api.riotpiao.com/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d 'not json'
+```
+
+#### Upstream Error
+
+**Status**: `5xx` (from upstream)
+
+**Trigger**: Upstream service error
+
+**Response**: Forwarded from upstream (unmodified)
+
+---
+
+## Examples
+
+### Test Script
+
+```bash
+#!/bin/bash
+
+GATEWAY="https://api.riotpiao.com"
+
+echo "=== Testing Gateway API ==="
+echo ""
+
+# Test 1: Health checks
+echo "1. Health checks"
+curl -s "$GATEWAY/healthz" | jq .
+curl -s "$GATEWAY/readyz" | jq .
+echo ""
+
+# Test 2: List models
+echo "2. List models"
+curl -s "$GATEWAY/v1/models" | jq '.data[] | .id'
+echo ""
+
+# Test 3: Chat with reasoning model
+echo "3. Chat with reasoning model"
+curl -s -X POST "$GATEWAY/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [{"role": "user", "content": "What is 2+2?"}]
+  }' | jq '.choices[0].message.content'
+echo ""
+
+# Test 4: Unknown model (should be 400)
+echo "4. Unknown model (should be 400)"
+curl -s -X POST "$GATEWAY/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gpt-4","messages":[]}' | jq '{status: .status, title: .title}'
+echo ""
+
+# Test 5: Embeddings
+echo "5. Embeddings"
+curl -s -X POST "$GATEWAY/v1/embeddings" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "nomic-ai/nomic-embed-text-v2-moe",
+    "input": "hello world"
+  }' | jq '.data | length'
+echo ""
+
+# Test 6: Rerank
+echo "6. Rerank"
+curl -s -X POST "$GATEWAY/v1/rerank" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "BAAI/bge-reranker-base",
+    "query": "test",
+    "texts": ["a", "b"]
+  }' | jq '.results | length'
+echo ""
+
+# Test 7: Streaming
+echo "7. Streaming (showing first 5 chunks)"
+curl -s -N -X POST "$GATEWAY/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [{"role": "user", "content": "hi"}],
+    "stream": true
+  }' | head -10
+echo ""
+
+echo "=== All tests completed ==="
+```
+
+### Python Client Example
+
+```python
+import requests
+import json
+
+GATEWAY = "https://api.riotpiao.com"
+
+# Get models
+response = requests.get(f"{GATEWAY}/v1/models")
+models = response.json()
+print(f"Available models: {[m['id'] for m in models['data']]}")
+
+# Chat completion
+response = requests.post(
+    f"{GATEWAY}/v1/chat/completions",
+    json={
+        "model": "reasoning",
+        "messages": [
+            {"role": "user", "content": "What is machine learning?"}
+        ]
+    }
+)
+message = response.json()
+print(f"Response: {message['choices'][0]['message']['content']}")
+
+# Chat with tools
+response = requests.post(
+    f"{GATEWAY}/v1/chat/completions",
+    json={
+        "model": "reasoning",
+        "messages": [
+            {"role": "user", "content": "Get the weather"}
+        ],
+        "tools": [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "parameters": {}
+                }
+            }
+        ]
+    }
+)
+result = response.json()
+if "tool_calls" in result["choices"][0]["message"]:
+    print(f"Tool calls: {result['choices'][0]['message']['tool_calls']}")
+
+# Streaming
+response = requests.post(
+    f"{GATEWAY}/v1/chat/completions",
+    json={
+        "model": "reasoning",
+        "messages": [
+            {"role": "user", "content": "Count to 3"}
+        ],
+        "stream": True
+    },
+    stream=True
+)
+for line in response.iter_lines():
+    if line:
+        print(line)
+
+# Embeddings
+response = requests.post(
+    f"{GATEWAY}/v1/embeddings",
+    json={
+        "model": "nomic-ai/nomic-embed-text-v2-moe",
+        "input": "hello world"
+    }
+)
+embeddings = response.json()
+print(f"Embeddings: {embeddings['data'][0]['embedding'][:5]}")
+
+# Rerank
+response = requests.post(
+    f"{GATEWAY}/v1/rerank",
+    json={
+        "model": "BAAI/bge-reranker-base",
+        "query": "ML",
+        "texts": ["machine learning", "python", "deep learning"]
+    }
+)
+results = response.json()
+print(f"Rerank results: {results['results']}")
+```
+
+### JavaScript/TypeScript Client Example
+
+```typescript
+const GATEWAY = "https://api.riotpiao.com";
+
+// Get models
+async function getModels() {
+  const response = await fetch(`${GATEWAY}/v1/models`);
+  const data = await response.json();
+  return data.data.map((m: any) => m.id);
+}
+
+// Chat completion
+async function chat(model: string, message: string) {
+  const response = await fetch(`${GATEWAY}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: "user", content: message }],
+    }),
+  });
+  const data = await response.json();
+  return data.choices[0].message.content;
+}
+
+// Chat with streaming
+async function chatStream(model: string, message: string) {
+  const response = await fetch(`${GATEWAY}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: "user", content: message }],
+      stream: true,
+    }),
+  });
+
+  const reader = response.body!.getReader();
+  const decoder = new TextDecoder();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value);
+    const lines = chunk.split("\n");
+    for (const line of lines) {
+      if (line.startsWith("data: ")) {
+        const data = JSON.parse(line.slice(6));
+        if (data.choices[0].delta?.content) {
+          console.log(data.choices[0].delta.content);
+        }
+      }
+    }
+  }
+}
+
+// Embeddings
+async function embed(model: string, input: string[]) {
+  const response = await fetch(`${GATEWAY}/v1/embeddings`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model, input }),
+  });
+  const data = await response.json();
+  return data.data;
+}
+
+// Rerank
+async function rerank(
+  model: string,
+  query: string,
+  texts: string[]
+) {
+  const response = await fetch(`${GATEWAY}/v1/rerank`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model, query, texts }),
+  });
+  const data = await response.json();
+  return data.results;
+}
+
+// Usage
+(async () => {
+  const models = await getModels();
+  console.log("Models:", models);
+
+  const response = await chat("reasoning", "What is AI?");
+  console.log("Response:", response);
+
+  await chatStream("reasoning", "Count to 3");
+
+  const embeddings = await embed("nomic-ai/nomic-embed-text-v2-moe", [
+    "hello",
+  ]);
+  console.log("Embeddings:", embeddings);
+
+  const rerankResults = await rerank("BAAI/bge-reranker-base", "ML", [
+    "machine learning",
+    "python",
+  ]);
+  console.log("Rerank:", rerankResults);
+})();
+```
+
+---
+
+## Rate Limiting
+
+Currently, no rate limiting is enforced. This will be added in Phase 4.
+
+---
+
+## Authentication
+
+Currently, no authentication is enforced. Bearer token support will be added in Phase 3.
+
+---
+
+## Timeouts
+
+Default timeouts per route:
+- **Connect**: 10s
+- **Read**: 1h (for streaming)
+- **Write**: 1h
+
+These are configured per model upstream.
+
+---
+
+## Body Size Limits
+
+- **Default**: 100MB
+- **Per-route**: Configurable
+
+Requests exceeding the limit return `413 Request Entity Too Large`.
+
+---
+
+## Support
+
+For issues or questions:
+- Check gateway logs: `kubectl -n api logs deployment/homelab-frontend`
+- Check health: `curl https://api.riotpiao.com/healthz`
+- Verify config: `curl https://api.riotpiao.com/v1/models`

TESTING_GUIDE.md

@@ -0,0 +1,560 @@
+# API Testing Guide
+
+Quick reference for testing the homelab-frontend gateway API.
+
+## Setup
+
+```bash
+# Set base URL
+export GATEWAY="https://api.riotpiao.com"
+
+# Or for local testing
+export GATEWAY="http://localhost:8080"
+```
+
+---
+
+## Quick Tests (Copy & Paste)
+
+### 1. Health Checks ✅
+
+```bash
+# Liveness
+curl $GATEWAY/healthz | jq .
+
+# Readiness
+curl $GATEWAY/readyz | jq .
+```
+
+**Expected**: Both return `{"status":"..."}` with HTTP 200
+
+---
+
+### 2. List Models ✅
+
+```bash
+curl $GATEWAY/v1/models | jq '.data[] | .id'
+```
+
+**Expected Output**:
+```
+"reasoning"
+"ornith:35b"
+"qwen2.5:3b-instruct"
+"nomic-ai/nomic-embed-text-v2-moe"
+"BAAI/bge-reranker-base"
+```
+
+---
+
+### 3. Chat - Basic ✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {"role": "user", "content": "What is 2+2?"}
+    ]
+  }' | jq '.choices[0].message.content'
+```
+
+**Expected**: Model responds with an answer
+
+---
+
+### 4. Chat - Ornith Model ✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "ornith:35b",
+    "messages": [
+      {"role": "user", "content": "Hello"}
+    ]
+  }' | jq '.choices[0].message.content'
+```
+
+**Expected**: Routes to ornith model, returns response
+
+---
+
+### 5. Chat - Qwen Model ✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "qwen2.5:3b-instruct",
+    "messages": [
+      {"role": "user", "content": "Hi"}
+    ]
+  }' | jq '.choices[0].message.content'
+```
+
+**Expected**: Routes to qwen model, returns response
+
+---
+
+### 6. Chat - Unknown Model (Should Error) ❌→✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gpt-4-turbo",
+    "messages": []
+  }' | jq '.'
+```
+
+**Expected**: HTTP 400 with problem+json:
+```json
+{
+  "type": "https://api.example.com/problems/unknown-model",
+  "title": "Unknown Model",
+  "status": 400,
+  "detail": "Model \"gpt-4-turbo\" is not available. See valid_models for available options.",
+  "valid_models": ["reasoning", "ornith:35b", ...]
+}
+```
+
+---
+
+### 7. Chat - Missing Model (Should Error) ❌→✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "messages": [{"role": "user", "content": "test"}]
+  }' | jq '.'
+```
+
+**Expected**: HTTP 400 with problem+json (missing model)
+
+---
+
+### 8. Chat - Streaming ✅
+
+```bash
+curl -N -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [{"role": "user", "content": "count to 3"}],
+    "stream": true
+  }' | head -20
+```
+
+**Expected**: 
+- Multiple `data: {...}` lines (SSE chunks)
+- Final `data: [DONE]`
+- Chunks arrive incrementally (observable with `-N` flag)
+
+---
+
+### 9. Chat - Tool Calling ✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [
+      {"role": "user", "content": "What is the weather in SF?"}
+    ],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "get_weather",
+          "description": "Get weather for a location",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "location": {"type": "string"}
+            },
+            "required": ["location"]
+          }
+        }
+      }
+    ]
+  }' | jq '.choices[0].message.tool_calls'
+```
+
+**Expected**: Array of tool calls (if model decides to call them), or null (if not)
+
+---
+
+### 10. Embeddings ✅
+
+```bash
+curl -X POST $GATEWAY/v1/embeddings \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "nomic-ai/nomic-embed-text-v2-moe",
+    "input": "hello world"
+  }' | jq '.data | length'
+```
+
+**Expected**: `1` (one embedding vector)
+
+---
+
+### 11. Embeddings - Multiple ✅
+
+```bash
+curl -X POST $GATEWAY/v1/embeddings \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "nomic-ai/nomic-embed-text-v2-moe",
+    "input": ["text 1", "text 2", "text 3"]
+  }' | jq '.data | length'
+```
+
+**Expected**: `3` (three embedding vectors)
+
+---
+
+### 12. Embeddings - Unknown Model (Should Error) ❌→✅
+
+```bash
+curl -X POST $GATEWAY/v1/embeddings \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "unknown-embed",
+    "input": "test"
+  }' | jq '.status'
+```
+
+**Expected**: `400` (client error)
+
+---
+
+### 13. Rerank ✅
+
+```bash
+curl -X POST $GATEWAY/v1/rerank \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "BAAI/bge-reranker-base",
+    "query": "machine learning",
+    "texts": [
+      "Machine learning is AI",
+      "Python is a language",
+      "Deep learning is ML"
+    ]
+  }' | jq '.results'
+```
+
+**Expected**: Array of ranked results with scores:
+```json
+[
+  {"index": 0, "score": 0.95},
+  {"index": 2, "score": 0.85},
+  {"index": 1, "score": 0.15}
+]
+```
+
+---
+
+### 14. Rerank - Unknown Model (Should Error) ❌→✅
+
+```bash
+curl -X POST $GATEWAY/v1/rerank \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "unknown-rerank",
+    "query": "test",
+    "texts": ["a"]
+  }' | jq '.status'
+```
+
+**Expected**: `400` (client error)
+
+---
+
+### 15. Invalid JSON (Should Error) ❌→✅
+
+```bash
+curl -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d 'not json' | jq '.title'
+```
+
+**Expected**: `"Invalid Request Body"` (HTTP 400)
+
+---
+
+## Testing Checklist
+
+Complete this checklist to verify all endpoints:
+
+### Health Endpoints
+- [ ] GET /healthz → 200, `{"status":"alive"}`
+- [ ] GET /readyz → 200, `{"status":"ready"}`
+
+### Model Discovery
+- [ ] GET /v1/models → 200, returns all 5 models
+- [ ] All advertised models can be called (none 400)
+
+### Chat Completions
+- [ ] POST /v1/chat/completions (reasoning) → 200, response
+- [ ] POST /v1/chat/completions (ornith:35b) → 200, response
+- [ ] POST /v1/chat/completions (qwen2.5:3b-instruct) → 200, response
+- [ ] POST /v1/chat/completions (unknown model) → 400, problem+json
+- [ ] POST /v1/chat/completions (missing model) → 400, problem+json
+- [ ] POST /v1/chat/completions (invalid JSON) → 400, problem+json
+- [ ] POST /v1/chat/completions (streaming) → 200, SSE chunks
+- [ ] POST /v1/chat/completions (with tools) → 200, tool_calls present/absent
+
+### Embeddings
+- [ ] POST /v1/embeddings (single input) → 200, embedding
+- [ ] POST /v1/embeddings (multiple inputs) → 200, embeddings array
+- [ ] POST /v1/embeddings (unknown model) → 400, problem+json
+
+### Reranking
+- [ ] POST /v1/rerank → 200, ranked results
+- [ ] POST /v1/rerank (unknown model) → 400, problem+json
+- [ ] Verify path is rewritten to /rerank on upstream
+
+### Error Handling
+- [ ] Unknown model lists valid_models
+- [ ] Error responses are problem+json
+- [ ] No 5xx for client errors (validation errors)
+- [ ] Upstream errors pass through
+
+### Streaming
+- [ ] Chunks arrive incrementally
+- [ ] Final `[DONE]` sentinel present
+- [ ] Works for chat completions
+
+### Tool Calling
+- [ ] Tool definitions forward to upstream
+- [ ] Tool calls in response
+- [ ] Multi-turn with tool results
+- [ ] Parallel tool calls
+- [ ] Complex nested arguments preserved
+
+---
+
+## Troubleshooting
+
+### 404 Responses
+
+**Symptom**: All endpoints return `"not found"`
+
+**Cause**: ConfigMap with models/routes not deployed
+
+**Solution**:
+```bash
+kubectl -n api create configmap homelab-frontend-config \
+  --from-file=config.yaml=k8s/configmap.yaml
+kubectl -n api rollout restart deployment/homelab-frontend
+```
+
+---
+
+### 503 (Not Ready)
+
+**Symptom**: `/readyz` returns 503
+
+**Cause**: Configuration not loaded or JWKS fetch failed
+
+**Solution**:
+```bash
+# Check logs
+kubectl -n api logs deployment/homelab-frontend
+
+# Check config
+kubectl -n api get configmap homelab-frontend-config
+```
+
+---
+
+### Connection Refused
+
+**Symptom**: `Connection refused` or `Temporary failure in name resolution`
+
+**Cause**: 
+- Gateway not running
+- Wrong URL/hostname
+- Network issue
+
+**Solution**:
+```bash
+# Verify gateway is running
+kubectl -n api get pods -l app=homelab-frontend
+
+# Check service
+kubectl -n api get svc homelab-frontend
+
+# Verify ingress
+kubectl -n api get ingress api
+```
+
+---
+
+### Upstream Connection Errors
+
+**Symptom**: `502 Bad Gateway` or `connection refused to upstream`
+
+**Cause**: Model upstream service not reachable
+
+**Solution**:
+```bash
+# Check upstreams are running
+kubectl -n llm-serving get pods
+
+# Verify addresses in ConfigMap
+kubectl -n api get configmap homelab-frontend-config -o yaml
+
+# Test connectivity from gateway pod
+kubectl -n api exec deployment/homelab-frontend -- \
+  curl -s reasoning-predictor.llm-serving:80/healthz
+```
+
+---
+
+### Streaming Doesn't Work
+
+**Symptom**: Chunks arrive all at once (buffered) instead of incrementally
+
+**Cause**: nginx buffering or client not using `-N` flag
+
+**Solution**:
+```bash
+# Use -N flag
+curl -N https://api.riotpiao.com/v1/chat/completions ...
+
+# Verify nginx has buffering disabled
+# Should have: proxy-buffering: off in Ingress annotations
+```
+
+---
+
+## Performance Testing
+
+### Load Test (Simple)
+
+```bash
+# Send 10 requests in parallel
+for i in {1..10}; do
+  curl -X POST $GATEWAY/v1/chat/completions \
+    -H 'Content-Type: application/json' \
+    -d '{"model":"reasoning","messages":[{"role":"user","content":"Hi"}]}' &
+done
+wait
+
+echo "Completed 10 requests"
+```
+
+### Concurrency Test
+
+```bash
+# Use Apache Bench (if installed)
+ab -n 100 -c 10 \
+  -p request.json \
+  -T application/json \
+  $GATEWAY/v1/chat/completions
+
+# Create request.json:
+# {"model":"reasoning","messages":[{"role":"user","content":"test"}]}
+```
+
+### Latency Test
+
+```bash
+# Measure response time
+curl -w "\nTotal time: %{time_total}s\n" \
+  -X POST $GATEWAY/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "reasoning",
+    "messages": [{"role": "user", "content": "What is AI?"}]
+  }' > /dev/null
+```
+
+---
+
+## Integration Testing
+
+### Test with Python
+
+```bash
+pip install requests
+
+cat > test_api.py << 'EOF'
+import requests
+import json
+
+gateway = "https://api.riotpiao.com"
+
+# Test health
+r = requests.get(f"{gateway}/healthz")
+assert r.status_code == 200
+print("✓ Health check passed")
+
+# Test models
+r = requests.get(f"{gateway}/v1/models")
+assert r.status_code == 200
+models = [m['id'] for m in r.json()['data']]
+print(f"✓ Models: {models}")
+
+# Test chat
+r = requests.post(
+    f"{gateway}/v1/chat/completions",
+    json={"model": "reasoning", "messages": [{"role": "user", "content": "Hi"}]}
+)
+assert r.status_code == 200
+print("✓ Chat works")
+
+# Test unknown model error
+r = requests.post(
+    f"{gateway}/v1/chat/completions",
+    json={"model": "gpt-4", "messages": []}
+)
+assert r.status_code == 400
+assert "unknown" in r.json()['detail'].lower()
+print("✓ Unknown model error correct")
+
+# Test embeddings
+r = requests.post(
+    f"{gateway}/v1/embeddings",
+    json={"model": "nomic-ai/nomic-embed-text-v2-moe", "input": "test"}
+)
+assert r.status_code == 200
+print("✓ Embeddings work")
+
+# Test rerank
+r = requests.post(
+    f"{gateway}/v1/rerank",
+    json={"model": "BAAI/bge-reranker-base", "query": "test", "texts": ["a", "b"]}
+)
+assert r.status_code == 200
+print("✓ Reranking works")
+
+print("\n✅ All tests passed!")
+EOF
+
+python test_api.py
+```
+
+---
+
+## Summary
+
+| Category | Tests | Expected |
+|----------|-------|----------|
+| Health | 2 | ✅ Both 200 |
+| Models | 1 | ✅ 5 models listed |
+| Chat | 8 | ✅ 6 success + 2 error |
+| Embeddings | 3 | ✅ 2 success + 1 error |
+| Rerank | 2 | ✅ 1 success + 1 error |
+| Streaming | 1 | ✅ Incremental chunks |
+| Tools | 1 | ✅ Tool calls present |
+| **TOTAL** | **18+** | **✅ ALL PASS** |
+
+Once all tests pass, the gateway is production-ready! 🚀

cmd/gateway/main.go

@@ -10,6 +10,7 @@ import (
 	"syscall"
 
 	"github.com/Riotpiaole/homelab-frontend/internal/config"
+	"github.com/Riotpiaole/homelab-frontend/internal/proxy"
 	"github.com/Riotpiaole/homelab-frontend/internal/server"
 )
 
@@ -30,11 +31,8 @@ func main() {
 		}
 	}
 
-	// Create a basic handler (will be replaced with real routing later)
-	upstreamHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusNotFound)
-		fmt.Fprintf(w, "not found")
-	})
+	// Create the reverse proxy handler that routes requests based on configuration
+	upstreamHandler := proxy.New(cfg)
 
 	// Create server with health checker
 	srv := server.New(cfg.ListenAddr, cfg.ShutdownTimeout, nil)

internal/proxy/bodydispatch_test.go

@@ -76,7 +76,10 @@ func TestBodyBasedDispatch(t *testing.T) {
 	reasoningCalled = false
 	ornithCalled = false
 	requestBody := `{"model":"reasoning","messages":[{"role":"user","content":"hi"}]}`
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	resp.Body.Close()
 
 	if !reasoningCalled {
@@ -151,7 +154,10 @@ func TestBodyPreservedUnmodified(t *testing.T) {
 
 	// Send a request with specific body content
 	originalBody := `{"model":"reasoning","stream":true,"messages":[{"role":"user","content":"hello world"}],"temperature":0.7}`
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(originalBody))
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(originalBody))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	resp.Body.Close()
 
 	if string(receivedBody) != originalBody {
@@ -223,7 +229,7 @@ func TestStreamingUnbuffered(t *testing.T) {
 	}
 }
 
-// TestUnknownModelReject verifies that unknown models are rejected.
+// TestUnknownModelReject verifies that unknown models are rejected with 400 and problem+json.
 func TestUnknownModelReject(t *testing.T) {
 	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
@@ -249,15 +255,35 @@ func TestUnknownModelReject(t *testing.T) {
 	defer server.Close()
 
 	requestBody := `{"model":"unknown-model","messages":[]}`
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
-	resp.Body.Close()
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
 
-	if resp.StatusCode != http.StatusNotFound {
-		t.Errorf("expected 404 for unknown model, got %d", resp.StatusCode)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("expected 400 for unknown model, got %d", resp.StatusCode)
+	}
+
+	// Verify problem+json content type
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected content-type application/problem+json, got %s", ct)
+	}
+
+	// Verify response is valid JSON
+	var prob map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&prob); err != nil {
+		t.Errorf("response is not valid JSON: %v", err)
+	}
+
+	// Verify valid_models is included
+	if prob["valid_models"] == nil {
+		t.Errorf("expected valid_models in problem detail")
 	}
 }
 
-// TestMissingModelField verifies that missing model field is rejected.
+// TestMissingModelField verifies that missing model field is rejected with 400 and problem+json.
 func TestMissingModelField(t *testing.T) {
 	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
@@ -283,11 +309,26 @@ func TestMissingModelField(t *testing.T) {
 	defer server.Close()
 
 	requestBody := `{"messages":[]}`
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
-	resp.Body.Close()
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", strings.NewReader(requestBody))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
 
-	if resp.StatusCode != http.StatusNotFound {
-		t.Errorf("expected 404 for missing model, got %d", resp.StatusCode)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("expected 400 for missing model, got %d", resp.StatusCode)
+	}
+
+	// Verify problem+json content type
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected content-type application/problem+json, got %s", ct)
+	}
+
+	// Verify response is valid JSON
+	var prob map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&prob); err != nil {
+		t.Errorf("response is not valid JSON: %v", err)
 	}
 }
 

internal/proxy/bodysize_test.go

@@ -323,7 +323,10 @@ func TestBodySizeCapRejectionLogged(t *testing.T) {
 
 	// Send an oversized body
 	body := strings.Repeat("a", int(maxBodySize)+1)
-	resp, _ := http.Post(server.URL+"/test", "text/plain", strings.NewReader(body))
+	resp, err := http.Post(server.URL+"/test", "text/plain", strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	resp.Body.Close()
 
 	// Verify rejection status

internal/proxy/embeddings_and_rerank_test.go

@@ -0,0 +1,420 @@
+package proxy
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/Riotpiaole/homelab-frontend/internal/config"
+)
+
+// TestEmbeddingsPassthroughNoRewrite verifies /v1/embeddings is not rewritten
+func TestEmbeddingsPassthroughNoRewrite(t *testing.T) {
+	embeddingsCalled := false
+	upstreamPath := ""
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		embeddingsCalled = true
+		upstreamPath = r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2]}]}`)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/embeddings",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"nomic-ai/nomic-embed-text-v2-moe","input":"hello"}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if !embeddingsCalled {
+		t.Errorf("upstream embeddings service was not called")
+	}
+
+	// Verify path is NOT rewritten (should stay /v1/embeddings)
+	if upstreamPath != "/v1/embeddings" {
+		t.Errorf("expected upstream path /v1/embeddings, got %s", upstreamPath)
+	}
+}
+
+// TestEmbeddingsResponsePassthrough verifies response body is unmodified
+func TestEmbeddingsResponsePassthrough(t *testing.T) {
+	expectedResponse := `{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2,0.3]}]}`
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, expectedResponse)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/embeddings",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"nomic-ai/nomic-embed-text-v2-moe","input":"test"}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+
+	if string(body) != expectedResponse {
+		t.Errorf("response was modified. Expected:\n%s\n\nGot:\n%s", expectedResponse, string(body))
+	}
+}
+
+// TestRerankPathRewrite verifies /v1/rerank is rewritten to /rerank
+func TestRerankPathRewrite(t *testing.T) {
+	upstreamPath := ""
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamPath = r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"results":[{"index":0,"score":0.9}]}`)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"BAAI/bge-reranker-base": {
+				Name:    "BAAI/bge-reranker-base",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/rerank",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"BAAI/bge-reranker-base","query":"test","texts":["a","b"]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	// Verify path IS rewritten to /rerank
+	if upstreamPath != "/rerank" {
+		t.Errorf("expected upstream path /rerank, got %s", upstreamPath)
+	}
+}
+
+// TestRerankResponsePassthrough verifies response is unmodified
+func TestRerankResponsePassthrough(t *testing.T) {
+	expectedResponse := `{"results":[{"index":0,"score":0.95},{"index":1,"score":0.85}]}`
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, expectedResponse)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"BAAI/bge-reranker-base": {
+				Name:    "BAAI/bge-reranker-base",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/rerank",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"BAAI/bge-reranker-base","query":"q","texts":["a"]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+
+	if string(body) != expectedResponse {
+		t.Errorf("response was modified")
+	}
+}
+
+// TestEmbeddingsUnknownModel returns error for unknown model
+func TestEmbeddingsUnknownModel(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/embeddings",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown-embeddings","input":"test"}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("expected 400 for unknown embeddings model, got %d", resp.StatusCode)
+	}
+
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected problem+json for unknown model")
+	}
+}
+
+// TestRerankerUnknownModel returns error for unknown model
+func TestRerankerUnknownModel(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"BAAI/bge-reranker-base": {
+				Name:    "BAAI/bge-reranker-base",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/rerank",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown-reranker","query":"q","texts":["a"]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("expected 400 for unknown reranker model, got %d", resp.StatusCode)
+	}
+}
+
+// TestEmbeddingsBodyForwarded verifies body is byte-identical to upstream
+func TestEmbeddingsBodyForwarded(t *testing.T) {
+	receivedBody := ""
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		receivedBody = string(body)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"object":"list","data":[]}`)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	originalBody := `{"model":"nomic-ai/nomic-embed-text-v2-moe","input":"test data with special chars: \u0001"}`
+	resp, err := http.Post(
+		server.URL+"/v1/embeddings",
+		"application/json",
+		bytes.NewReader([]byte(originalBody)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	// The received body should match the original (though may have different formatting)
+	var orig, received map[string]interface{}
+	json.Unmarshal([]byte(originalBody), &orig)
+	json.Unmarshal([]byte(receivedBody), &received)
+
+	if orig["model"] != received["model"] || orig["input"] != received["input"] {
+		t.Errorf("body was not forwarded correctly")
+	}
+}
+
+// TestRerankerBodyForwarded verifies body is byte-identical to upstream
+func TestRerankerBodyForwarded(t *testing.T) {
+	receivedBody := ""
+
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		receivedBody = string(body)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"results":[]}`)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"BAAI/bge-reranker-base": {
+				Name:    "BAAI/bge-reranker-base",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	originalBody := `{"model":"BAAI/bge-reranker-base","query":"test","texts":["a","b","c"]}`
+	resp, err := http.Post(
+		server.URL+"/v1/rerank",
+		"application/json",
+		bytes.NewReader([]byte(originalBody)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+
+	var orig, received map[string]interface{}
+	json.Unmarshal([]byte(originalBody), &orig)
+	json.Unmarshal([]byte(receivedBody), &received)
+
+	if orig["model"] != received["model"] || orig["query"] != received["query"] {
+		t.Errorf("body was not forwarded correctly")
+	}
+}
+
+// TestUpstreamErrorStatusSurfaced verifies upstream errors are returned as-is
+func TestUpstreamErrorStatusSurfaced(t *testing.T) {
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		fmt.Fprint(w, `{"error":"upstream failure"}`)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/embeddings",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"nomic-ai/nomic-embed-text-v2-moe","input":"test"}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Errorf("expected upstream error status 500, got %d", resp.StatusCode)
+	}
+}

internal/proxy/headers_test.go

@@ -71,7 +71,7 @@ func TestHeaderHygiene(t *testing.T) {
 			t.Errorf("hop-by-hop header %s should be stripped, but found: %s", header, receivedHeaders.Get(header))
 		}
 	}
-	
+
 	// TE header is tricky - it should be stripped but may be handled differently
 	// Just verify it's not the original value for now
 	if receivedHeaders.Get("TE") == "trailers" {

internal/proxy/models_endpoint_test.go

@@ -0,0 +1,470 @@
+package proxy
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sort"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Riotpiaole/homelab-frontend/internal/config"
+)
+
+// ModelListResponse represents the response shape for GET /v1/models
+type ModelListResponse struct {
+	Object string       `json:"object"`
+	Data   []ModelEntry `json:"data"`
+}
+
+// ModelEntry represents a single model in the list
+type ModelEntry struct {
+	ID      string `json:"id"`
+	Object  string `json:"object"`
+	OwnedBy string `json:"owned_by"`
+	Created int64  `json:"created"`
+}
+
+// TestModelsEndpointReturns200 verifies GET /v1/models returns 200
+func TestModelsEndpointReturns200(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+// TestModelsEndpointContentType verifies correct content type
+func TestModelsEndpointContentType(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/json") {
+		t.Errorf("expected content-type application/json, got %s", ct)
+	}
+}
+
+// TestModelsEndpointResponseShape verifies correct JSON structure
+func TestModelsEndpointResponseShape(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var result ModelListResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if result.Object != "list" {
+		t.Errorf("expected object='list', got %q", result.Object)
+	}
+
+	if len(result.Data) != 1 {
+		t.Errorf("expected 1 model, got %d", len(result.Data))
+	}
+
+	model := result.Data[0]
+	if model.ID != "reasoning" {
+		t.Errorf("expected id='reasoning', got %q", model.ID)
+	}
+
+	if model.Object != "model" {
+		t.Errorf("expected object='model', got %q", model.Object)
+	}
+}
+
+// TestModelsEndpointEnumeratesAllModels verifies all models are listed
+func TestModelsEndpointEnumeratesAllModels(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+			"ornith:35b": {
+				Name:    "ornith:35b",
+				Address: "localhost:9000",
+			},
+			"qwen2.5:3b-instruct": {
+				Name:    "qwen2.5:3b-instruct",
+				Address: "localhost:9000",
+			},
+			"nomic-ai/nomic-embed-text-v2-moe": {
+				Name:    "nomic-ai/nomic-embed-text-v2-moe",
+				Address: "localhost:9000",
+			},
+			"BAAI/bge-reranker-base": {
+				Name:    "BAAI/bge-reranker-base",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var result ModelListResponse
+	json.NewDecoder(resp.Body).Decode(&result)
+
+	if len(result.Data) != 5 {
+		t.Errorf("expected 5 models, got %d", len(result.Data))
+	}
+
+	// Collect actual model IDs
+	modelIDs := make(map[string]bool)
+	for _, model := range result.Data {
+		modelIDs[model.ID] = true
+	}
+
+	// Verify all expected models are present
+	expectedModels := []string{
+		"reasoning",
+		"ornith:35b",
+		"qwen2.5:3b-instruct",
+		"nomic-ai/nomic-embed-text-v2-moe",
+		"BAAI/bge-reranker-base",
+	}
+
+	for _, expected := range expectedModels {
+		if !modelIDs[expected] {
+			t.Errorf("expected model %q in response", expected)
+		}
+	}
+}
+
+// TestModelsEndpointHasRequiredFields verifies all required fields are present
+func TestModelsEndpointHasRequiredFields(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var result ModelListResponse
+	json.NewDecoder(resp.Body).Decode(&result)
+
+	model := result.Data[0]
+	if model.ID == "" {
+		t.Errorf("expected id field")
+	}
+
+	if model.Object == "" {
+		t.Errorf("expected object field")
+	}
+
+	if model.OwnedBy == "" {
+		t.Errorf("expected owned_by field")
+	}
+
+	if model.Created == 0 {
+		t.Errorf("expected created field (unix timestamp)")
+	}
+}
+
+// TestModelsEndpointNoUpstreamContact verifies endpoint doesn't contact upstream
+func TestModelsEndpointNoUpstreamContact(t *testing.T) {
+	upstreamCalled := false
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamCalled = true
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	_, _ = http.Get(server.URL + "/v1/models")
+
+	if upstreamCalled {
+		t.Errorf("upstream should not be called for /v1/models endpoint")
+	}
+}
+
+// TestModelsEndpointDerivedFromConfig verifies models come from config, not hardcoded
+func TestModelsEndpointDerivedFromConfig(t *testing.T) {
+	// Create config with specific models
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"custom-model-1": {
+				Name:    "custom-model-1",
+				Address: "localhost:9000",
+			},
+			"custom-model-2": {
+				Name:    "custom-model-2",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var result ModelListResponse
+	json.NewDecoder(resp.Body).Decode(&result)
+
+	// Verify only the configured models are returned
+	if len(result.Data) != 2 {
+		t.Errorf("expected 2 models from config, got %d", len(result.Data))
+	}
+
+	modelIDs := make([]string, len(result.Data))
+	for i, model := range result.Data {
+		modelIDs[i] = model.ID
+	}
+	sort.Strings(modelIDs)
+
+	expected := []string{"custom-model-1", "custom-model-2"}
+	if !equal(modelIDs, expected) {
+		t.Errorf("expected models %v, got %v", expected, modelIDs)
+	}
+}
+
+// TestModelsEndpointConsistentWithDispatch verifies advertised models can dispatch
+func TestModelsEndpointConsistentWithDispatch(t *testing.T) {
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: upstreamAddr,
+			},
+			"ornith:35b": {
+				Name:    "ornith:35b",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Get list of models
+	resp, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	var result ModelListResponse
+	json.NewDecoder(resp.Body).Decode(&result)
+	resp.Body.Close()
+
+	// Try to dispatch to each advertised model
+	for _, model := range result.Data {
+		dispatchResp, err := http.Post(
+			server.URL+"/v1/chat/completions",
+			"application/json",
+			strings.NewReader(`{"model":"`+model.ID+`","messages":[]}`),
+		)
+		if err != nil {
+			t.Fatalf("request failed: %v", err)
+		}
+		defer dispatchResp.Body.Close()
+
+		// Should not return 400 (unknown model error)
+		if dispatchResp.StatusCode == http.StatusBadRequest {
+			body, _ := io.ReadAll(dispatchResp.Body)
+			if strings.Contains(string(body), "unknown model") {
+				t.Errorf("model %q advertised in /v1/models but not accepted for dispatch", model.ID)
+			}
+		}
+	}
+}
+
+// TestModelsEndpointResponseIsConsistent verifies response is consistent across calls
+func TestModelsEndpointResponseIsConsistent(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "localhost:9000",
+			},
+			"ornith:35b": {
+				Name:    "ornith:35b",
+				Address: "localhost:9000",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Call endpoint twice
+	resp1, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	var result1 ModelListResponse
+	json.NewDecoder(resp1.Body).Decode(&result1)
+	resp1.Body.Close()
+
+	time.Sleep(10 * time.Millisecond)
+
+	resp2, err := http.Get(server.URL + "/v1/models")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	var result2 ModelListResponse
+	json.NewDecoder(resp2.Body).Decode(&result2)
+	resp2.Body.Close()
+
+	// Verify both responses have same models
+	if len(result1.Data) != len(result2.Data) {
+		t.Errorf("response length inconsistent: %d vs %d", len(result1.Data), len(result2.Data))
+	}
+
+	ids1 := make([]string, len(result1.Data))
+	ids2 := make([]string, len(result2.Data))
+
+	for i, m := range result1.Data {
+		ids1[i] = m.ID
+	}
+	for i, m := range result2.Data {
+		ids2[i] = m.ID
+	}
+
+	sort.Strings(ids1)
+	sort.Strings(ids2)
+
+	if !equal(ids1, ids2) {
+		t.Errorf("responses differ: %v vs %v", ids1, ids2)
+	}
+}
+
+// Helper function to compare string slices
+func equal(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

internal/proxy/proxy.go

@@ -2,12 +2,14 @@
 package proxy
 
 import (
+	"encoding/json"
 	"fmt"
 	"io"
 	"net"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
+	"sort"
 	"strings"
 	"time"
 
@@ -37,6 +39,26 @@ type Route struct {
 	Transport *http.Transport
 }
 
+// Error types for model validation
+type modelValidationError struct {
+	Kind    string // "invalid_json", "missing_model", "unknown_model"
+	Message string
+	Model   string // only for unknown_model
+}
+
+func (e *modelValidationError) Error() string {
+	return e.Message
+}
+
+// RFC 9457 Problem Details
+type problemDetail struct {
+	Type       string        `json:"type"`
+	Title      string        `json:"title"`
+	Status     int           `json:"status"`
+	Detail     string        `json:"detail"`
+	ValidModels []string     `json:"valid_models,omitempty"`
+}
+
 // New creates a new reverse proxy handler from configuration.
 // It sets up connection pooling and rewriting rules for each route.
 func New(cfg *config.Config) *Handler {
@@ -174,10 +196,79 @@ func getPeerIP(remoteAddr string) string {
 	return remoteAddr
 }
 
+// writeProblemDetail writes an RFC 9457 problem detail response.
+func writeProblemDetail(w http.ResponseWriter, status int, problemType, title, detail string, validModels []string) {
+	w.Header().Set("Content-Type", "application/problem+json")
+	w.WriteHeader(status)
+
+	problem := problemDetail{
+		Type:        problemType,
+		Title:       title,
+		Status:      status,
+		Detail:      detail,
+		ValidModels: validModels,
+	}
+
+	json.NewEncoder(w).Encode(problem)
+}
+
 // ServeHTTP implements http.Handler.
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// Handle /v1/models endpoint (no routing needed, derived from config)
+	if r.URL.Path == "/v1/models" && r.Method == "GET" {
+		h.handleModelsEndpoint(w, r)
+		return
+	}
+
 	// Try to find a matching route (including body-based dispatch for /v1/chat/completions)
 	route, err := h.RouteRequest(r)
+
+	// Check if this is a model validation error (from body-based dispatch)
+	if validationErr, ok := err.(*modelValidationError); ok {
+		// This is a client error, not a routing error
+		var status int
+		var problemType string
+		var title string
+		var detail string
+
+		switch validationErr.Kind {
+		case "invalid_json":
+			status = http.StatusBadRequest
+			problemType = "https://api.example.com/problems/invalid-request-body"
+			title = "Invalid Request Body"
+			detail = validationErr.Message
+		case "missing_model", "empty_model", "null_model":
+			status = http.StatusBadRequest
+			problemType = "https://api.example.com/problems/missing-model"
+			title = "Missing Model"
+			detail = "The 'model' field is required and must be a non-empty string"
+		case "unknown_model":
+			status = http.StatusBadRequest
+			problemType = "https://api.example.com/problems/unknown-model"
+			title = "Unknown Model"
+			detail = fmt.Sprintf("Model %q is not available. See valid_models for available options.", validationErr.Model)
+		default:
+			status = http.StatusBadRequest
+			problemType = "https://api.example.com/problems/invalid-request"
+			title = "Invalid Request"
+			detail = validationErr.Message
+		}
+
+		// Get list of valid models (only for model-related errors)
+		var validModels []string
+		if validationErr.Kind == "unknown_model" || validationErr.Kind == "missing_model" || validationErr.Kind == "empty_model" || validationErr.Kind == "null_model" {
+			validModels = h.getValidModels()
+		}
+
+		writeProblemDetail(w, status, problemType, title, detail, validModels)
+		logging.Errorf("client error", validationErr, map[string]string{
+			"path":   r.URL.Path,
+			"method": r.Method,
+			"reason": validationErr.Kind,
+		})
+		return
+	}
+
 	if err != nil || route == nil {
 		// Route not found or error determining route
 		w.WriteHeader(http.StatusNotFound)
@@ -252,6 +343,57 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 
 
 
+// getValidModels returns a sorted list of all configured model names.
+func (h *Handler) getValidModels() []string {
+	var models []string
+	for name := range h.config.Models {
+		models = append(models, name)
+	}
+	sort.Strings(models)
+	return models
+}
+
+// modelsListResponse represents the response for GET /v1/models
+type modelsListResponse struct {
+	Object string              `json:"object"`
+	Data   []modelsListEntry   `json:"data"`
+}
+
+// modelsListEntry represents a single model in the list
+type modelsListEntry struct {
+	ID      string `json:"id"`
+	Object  string `json:"object"`
+	OwnedBy string `json:"owned_by"`
+	Created int64  `json:"created"`
+}
+
+// handleModelsEndpoint serves GET /v1/models
+// Returns a list of all configured models, derived from config not hardcoded
+func (h *Handler) handleModelsEndpoint(w http.ResponseWriter, r *http.Request) {
+	// Get all model names from config
+	modelNames := h.getValidModels()
+
+	// Build the response
+	data := make([]modelsListEntry, len(modelNames))
+	for i, name := range modelNames {
+		data[i] = modelsListEntry{
+			ID:      name,
+			Object:  "model",
+			OwnedBy: "api.riotpiao.com",
+			Created: 1700000000, // Fixed timestamp; can be made configurable if needed
+		}
+	}
+
+	response := modelsListResponse{
+		Object: "list",
+		Data:   data,
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(response)
+}
+
 // Close closes all underlying transports, releasing their connection pools.
 func (h *Handler) Close() error {
 	for _, transport := range h.transports {

internal/proxy/proxy_test.go

@@ -105,7 +105,9 @@ func TestProxyPathRewrite(t *testing.T) {
 	server := httptest.NewServer(handler)
 	defer server.Close()
 
-	resp, err := http.Get(server.URL + "/v1/models")
+	// Not /v1/models: ServeHTTP serves that endpoint from config (task 2.5)
+	// and returns before routing, so it never exercises PathRewrite.
+	resp, err := http.Get(server.URL + "/some/path")
 	if err != nil {
 		t.Fatalf("request failed: %v", err)
 	}
@@ -146,7 +148,7 @@ func TestProxyConnectionReuse(t *testing.T) {
 	defer handler.Close()
 
 	// Verify connection reuse by checking that the same transport is used
-	
+
 	// We can't easily count raw TCP connections in this test setup,
 	// but we can verify that the transport is being reused by checking
 	// that the same transport handles both requests
@@ -402,7 +404,10 @@ func TestProxyPreservesBody(t *testing.T) {
 	defer server.Close()
 
 	testBody := `{"model": "test", "messages": []}`
-	resp, _ := http.Post(server.URL+"/test", "application/json", strings.NewReader(testBody))
+	resp, err := http.Post(server.URL+"/test", "application/json", strings.NewReader(testBody))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	resp.Body.Close()
 
 	if receivedBody != testBody {

internal/proxy/router.go

@@ -13,12 +13,12 @@ import (
 )
 
 // RouteRequest determines which upstream should handle the request.
-// For /v1/chat/completions, it uses body-based dispatch (reads JSON to find "model" field).
-// For other routes, it looks up by path prefix.
+// For /v1/chat/completions, /v1/embeddings, and /v1/rerank, it uses body-based dispatch.
+// For other routes, it looks up by path in the configured routes.
 func (h *Handler) RouteRequest(r *http.Request) (*Route, error) {
-	// For /v1/chat/completions, use body-based dispatch
-	if r.URL.Path == "/v1/chat/completions" && r.Method == "POST" {
-		return h.routeByModel(r)
+	// For /v1/chat/completions, /v1/embeddings, /v1/rerank use body-based dispatch
+	if r.Method == "POST" && (r.URL.Path == "/v1/chat/completions" || r.URL.Path == "/v1/embeddings" || r.URL.Path == "/v1/rerank") {
+		return h.routeByModel(r, r.URL.Path)
 	}
 
 	// For other paths, try to find a matching route by path
@@ -45,17 +45,25 @@ func (h *Handler) RouteRequest(r *http.Request) (*Route, error) {
 
 // routeByModel reads the request body to find the "model" field and routes accordingly.
 // The body is preserved for forwarding to the upstream.
-func (h *Handler) routeByModel(r *http.Request) (*Route, error) {
+// Returns a modelValidationError for client errors (invalid JSON, missing/unknown model).
+// The path parameter indicates which endpoint is being called (/v1/chat/completions, /v1/embeddings, /v1/rerank)
+func (h *Handler) routeByModel(r *http.Request, path string) (*Route, error) {
 	// If there's no body, we can't determine the model
 	if r.Body == nil {
-		return nil, fmt.Errorf("request body required")
+		return nil, &modelValidationError{
+			Kind:    "missing_model",
+			Message: "request body required",
+		}
 	}
 
 	// Read the body to extract the model name
 	// We need to be careful to preserve the body for the upstream
 	bodyBytes, err := io.ReadAll(r.Body)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read request body: %w", err)
+		return nil, &modelValidationError{
+			Kind:    "invalid_request",
+			Message: fmt.Sprintf("failed to read request body: %v", err),
+		}
 	}
 
 	// Restore the body so it can be read again by the upstream
@@ -64,26 +72,68 @@ func (h *Handler) routeByModel(r *http.Request) (*Route, error) {
 	// Parse the JSON to find the model field
 	var payload map[string]interface{}
 	if err := json.Unmarshal(bodyBytes, &payload); err != nil {
-		return nil, fmt.Errorf("invalid JSON in request body: %w", err)
+		return nil, &modelValidationError{
+			Kind:    "invalid_json",
+			Message: "request body is not valid JSON",
+		}
 	}
 
 	// Extract the model name
-	modelName, ok := payload["model"].(string)
+	modelVal, hasModel := payload["model"]
+	if !hasModel {
+		return nil, &modelValidationError{
+			Kind:    "missing_model",
+			Message: "'model' field is missing",
+		}
+	}
+
+	// Handle null model
+	if modelVal == nil {
+		return nil, &modelValidationError{
+			Kind:    "null_model",
+			Message: "'model' field is null",
+		}
+	}
+
+	// Extract as string
+	modelName, ok := modelVal.(string)
 	if !ok {
-		return nil, fmt.Errorf("model field missing or not a string")
+		return nil, &modelValidationError{
+			Kind:    "missing_model",
+			Message: "'model' field must be a string",
+		}
+	}
+
+	// Handle empty string
+	if modelName == "" {
+		return nil, &modelValidationError{
+			Kind:    "empty_model",
+			Message: "'model' field cannot be empty",
+		}
 	}
 
 	// Look up the model in the registry
 	modelUpstream := h.config.LookupModel(modelName)
 	if modelUpstream == nil {
-		return nil, fmt.Errorf("unknown model: %q", modelName)
+		return nil, &modelValidationError{
+			Kind:    "unknown_model",
+			Message: fmt.Sprintf("unknown model: %q", modelName),
+			Model:   modelName,
+		}
+	}
+
+	// Determine the upstream path based on the request path
+	upstreamPath := path
+	if path == "/v1/rerank" {
+		// Rerank endpoint uses /rerank path on upstream
+		upstreamPath = "/rerank"
 	}
 
 	// Create a route for this model with appropriate timeouts
 	// These are sensible defaults for LLM models
 	upstreamCfg := &config.Upstream{
 		Address:        modelUpstream.Address,
-		PathRewrite:    "/v1/chat/completions",
+		PathRewrite:    upstreamPath,
 		ConnectTimeout: h.defaultConnectTimeout,
 		ReadTimeout:    h.defaultReadTimeout,
 		WriteTimeout:   h.defaultWriteTimeout,

internal/proxy/timeout_test.go

@@ -102,7 +102,10 @@ func TestReadTimeout(t *testing.T) {
 	defer server.Close()
 
 	start := time.Now()
-	resp, _ := http.Get(server.URL + "/test")
+	resp, err := http.Get(server.URL + "/test")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	elapsed := time.Since(start)
 
 	// Should timeout around the read timeout (with some tolerance)

internal/proxy/toolcall_test.go

@@ -16,8 +16,8 @@ import (
 
 // OpenAI-style tool definition
 type Tool struct {
-	Type     string                 `json:"type"`
-	Function ToolFunction           `json:"function"`
+	Type     string       `json:"type"`
+	Function ToolFunction `json:"function"`
 }
 
 type ToolFunction struct {
@@ -28,21 +28,21 @@ type ToolFunction struct {
 
 // OpenAI chat completion with tools request
 type ChatCompletionRequest struct {
-	Model    string                 `json:"model"`
-	Messages []Message              `json:"messages"`
-	Tools    []Tool                 `json:"tools,omitempty"`
-	Stream   bool                   `json:"stream,omitempty"`
+	Model    string    `json:"model"`
+	Messages []Message `json:"messages"`
+	Tools    []Tool    `json:"tools,omitempty"`
+	Stream   bool      `json:"stream,omitempty"`
 }
 
 type Message struct {
-	Role      string        `json:"role"`
-	Content   interface{}   `json:"content"`
-	ToolCalls []ToolCall    `json:"tool_calls,omitempty"`
+	Role      string      `json:"role"`
+	Content   interface{} `json:"content"`
+	ToolCalls []ToolCall  `json:"tool_calls,omitempty"`
 }
 
 type ToolCall struct {
-	ID       string      `json:"id"`
-	Type     string      `json:"type"`
+	ID       string       `json:"id"`
+	Type     string       `json:"type"`
 	Function FunctionCall `json:"function"`
 }
 
@@ -64,21 +64,21 @@ func TestToolCallOpenAIStyle(t *testing.T) {
 		w.WriteHeader(http.StatusOK)
 
 		response := map[string]interface{}{
-			"id":      "chatcmpl-123",
-			"object":  "chat.completion",
-			"model":   "reasoning",
+			"id":     "chatcmpl-123",
+			"object": "chat.completion",
+			"model":  "reasoning",
 			"choices": []map[string]interface{}{
 				{
 					"index": 0,
 					"message": map[string]interface{}{
-						"role": "assistant",
+						"role":    "assistant",
 						"content": nil,
 						"tool_calls": []map[string]interface{}{
 							{
-								"id": "call_abc123",
+								"id":   "call_abc123",
 								"type": "function",
 								"function": map[string]interface{}{
-									"name": "get_weather",
+									"name":      "get_weather",
 									"arguments": `{"location":"San Francisco","unit":"celsius"}`,
 								},
 							},
@@ -372,10 +372,10 @@ func TestToolCallMultiTurn(t *testing.T) {
 							"content": nil,
 							"tool_calls": []map[string]interface{}{
 								{
-									"id": "call_abc123",
+									"id":   "call_abc123",
 									"type": "function",
 									"function": map[string]interface{}{
-										"name": "get_weather",
+										"name":      "get_weather",
 										"arguments": `{"location":"San Francisco"}`,
 									},
 								},
@@ -430,7 +430,10 @@ func TestToolCallMultiTurn(t *testing.T) {
 	}
 
 	body1, _ := json.Marshal(turn1)
-	resp1, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body1))
+	resp1, err := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body1))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	var turn1Resp map[string]interface{}
 	json.NewDecoder(resp1.Body).Decode(&turn1Resp)
 	resp1.Body.Close()
@@ -472,7 +475,10 @@ func TestToolCallMultiTurn(t *testing.T) {
 	}
 
 	body2, _ := json.Marshal(turn2)
-	resp2, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body2))
+	resp2, err := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body2))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	var turn2Resp map[string]interface{}
 	json.NewDecoder(resp2.Body).Decode(&turn2Resp)
 	resp2.Body.Close()
@@ -503,7 +509,7 @@ func TestParallelToolCalls(t *testing.T) {
 						"content": nil,
 						"tool_calls": []map[string]interface{}{
 							{
-								"id": "call_1",
+								"id":   "call_1",
 								"type": "function",
 								"function": map[string]interface{}{
 									"name":      "get_weather",
@@ -511,7 +517,7 @@ func TestParallelToolCalls(t *testing.T) {
 								},
 							},
 							{
-								"id": "call_2",
+								"id":   "call_2",
 								"type": "function",
 								"function": map[string]interface{}{
 									"name":      "get_weather",
@@ -519,7 +525,7 @@ func TestParallelToolCalls(t *testing.T) {
 								},
 							},
 							{
-								"id": "call_3",
+								"id":   "call_3",
 								"type": "function",
 								"function": map[string]interface{}{
 									"name":      "get_weather",
@@ -576,7 +582,10 @@ func TestParallelToolCalls(t *testing.T) {
 	}
 
 	body, _ := json.Marshal(request)
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body))
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	var respData map[string]interface{}
 	json.NewDecoder(resp.Body).Decode(&respData)
 	resp.Body.Close()
@@ -627,9 +636,9 @@ func TestAnthropicToolUse(t *testing.T) {
 
 		// Anthropic response format with tool_use block
 		response := map[string]interface{}{
-			"id":      "msg_123",
-			"type":    "message",
-			"role":    "assistant",
+			"id":   "msg_123",
+			"type": "message",
+			"role": "assistant",
 			"content": []map[string]interface{}{
 				{
 					"type": "text",
@@ -714,7 +723,10 @@ func TestAnthropicToolUse(t *testing.T) {
 	body, _ := json.Marshal(anthropicRequest)
 	// Note: For now we route through a generic path
 	// In Phase 2.9+, this would be integrated with the Anthropic dialect handler
-	resp, _ := http.Post(server.URL+"/v1/messages", "application/json", bytes.NewReader(body))
+	resp, err := http.Post(server.URL+"/v1/messages", "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	var respData map[string]interface{}
 	json.NewDecoder(resp.Body).Decode(&respData)
 	resp.Body.Close()
@@ -762,7 +774,7 @@ func TestComplexToolArguments(t *testing.T) {
 						"content": nil,
 						"tool_calls": []map[string]interface{}{
 							{
-								"id": "call_complex",
+								"id":   "call_complex",
 								"type": "function",
 								"function": map[string]interface{}{
 									"name": "create_event",
@@ -832,7 +844,10 @@ func TestComplexToolArguments(t *testing.T) {
 	}
 
 	body, _ := json.Marshal(request)
-	resp, _ := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body))
+	resp, err := http.Post(server.URL+"/v1/chat/completions", "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
 	var respData map[string]interface{}
 	json.NewDecoder(resp.Body).Decode(&respData)
 	resp.Body.Close()

internal/proxy/unknown_model_test.go

@@ -0,0 +1,513 @@
+package proxy
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/Riotpiaole/homelab-frontend/internal/config"
+)
+
+// RFC 9457 Problem Details
+type ProblemDetail struct {
+	Type     string                 `json:"type"`
+	Title    string                 `json:"title"`
+	Status   int                    `json:"status"`
+	Detail   string                 `json:"detail"`
+	Instance string                 `json:"instance,omitempty"`
+	Extra    map[string]interface{} `json:"-"`
+}
+
+// UnmarshalJSON allows capturing extra fields
+func (p *ProblemDetail) UnmarshalJSON(data []byte) error {
+	type Alias ProblemDetail
+	aux := &struct {
+		*Alias
+	}{
+		Alias: (*Alias)(p),
+	}
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+
+	// Capture extra fields
+	var raw map[string]interface{}
+	json.Unmarshal(data, &raw)
+	extra := make(map[string]interface{})
+	for k, v := range raw {
+		if k != "type" && k != "title" && k != "status" && k != "detail" && k != "instance" {
+			extra[k] = v
+		}
+	}
+	p.Extra = extra
+	return nil
+}
+
+// TestUnknownModelReturns4xx verifies unknown model returns client error
+func TestUnknownModelReturns4xx(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+				Path:    "/v1/chat/completions",
+			},
+			"ornith:35b": {
+				Name:    "ornith:35b",
+				Address: "ornith-predictor:80",
+				Path:    "/v1/chat/completions",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"gpt-4","messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	// Verify 4xx status
+	if resp.StatusCode < 400 || resp.StatusCode >= 500 {
+		t.Errorf("expected 4xx status for unknown model, got %d", resp.StatusCode)
+	}
+
+	// Verify RFC 9457 content type
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected content-type application/problem+json, got %s", ct)
+	}
+
+	// Verify response is valid problem detail
+	var prob ProblemDetail
+	body, _ := io.ReadAll(resp.Body)
+	if err := json.Unmarshal(body, &prob); err != nil {
+		t.Errorf("response is not valid JSON: %v", err)
+	}
+
+	if prob.Status == 0 {
+		t.Errorf("expected status in problem detail")
+	}
+
+	if prob.Title == "" {
+		t.Errorf("expected title in problem detail")
+	}
+}
+
+// TestUnknownModelEnumeratesValidModels verifies all models are listed
+func TestUnknownModelEnumeratesValidModels(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+			"ornith:35b": {
+				Name:    "ornith:35b",
+				Address: "ornith-predictor:80",
+			},
+			"qwen2.5:3b-instruct": {
+				Name:    "qwen2.5:3b-instruct",
+				Address: "ornith-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown","messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var prob map[string]interface{}
+	json.NewDecoder(resp.Body).Decode(&prob)
+
+	// Check for valid_models field (as an extra field beyond RFC 9457)
+	validModels, hasModels := prob["valid_models"]
+	if !hasModels {
+		t.Errorf("expected valid_models field in problem detail")
+		return
+	}
+
+	models := validModels.([]interface{})
+	if len(models) != 3 {
+		t.Errorf("expected 3 models in valid_models, got %d", len(models))
+	}
+
+	modelNames := make(map[string]bool)
+	for _, m := range models {
+		modelNames[m.(string)] = true
+	}
+
+	expectedModels := []string{"reasoning", "ornith:35b", "qwen2.5:3b-instruct"}
+	for _, expected := range expectedModels {
+		if !modelNames[expected] {
+			t.Errorf("expected model %s in valid_models", expected)
+		}
+	}
+}
+
+// TestMissingModelFieldReturns4xx verifies missing model field is client error
+func TestMissingModelFieldReturns4xx(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Request with no model field
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 400 || resp.StatusCode >= 500 {
+		t.Errorf("expected 4xx for missing model, got %d", resp.StatusCode)
+	}
+
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected problem+json for missing model")
+	}
+
+	// Verify body does not contain the request
+	body, _ := io.ReadAll(resp.Body)
+	if strings.Contains(string(body), "messages") {
+		t.Errorf("response should not echo request body")
+	}
+}
+
+// TestNullModelFieldReturns4xx verifies null model is client error
+func TestNullModelFieldReturns4xx(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Request with null model
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":null,"messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 400 || resp.StatusCode >= 500 {
+		t.Errorf("expected 4xx for null model, got %d", resp.StatusCode)
+	}
+
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/problem+json") {
+		t.Errorf("expected problem+json for null model")
+	}
+}
+
+// TestEmptyModelFieldReturns4xx verifies empty model string is client error
+func TestEmptyModelFieldReturns4xx(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Request with empty model string
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"","messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 400 || resp.StatusCode >= 500 {
+		t.Errorf("expected 4xx for empty model, got %d", resp.StatusCode)
+	}
+}
+
+// TestInvalidJSONIsDistinguishableError verifies invalid JSON is separate from unknown model
+func TestInvalidJSONIsDistinguishableError(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Request with invalid JSON
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`not json`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 400 || resp.StatusCode >= 500 {
+		t.Errorf("expected 4xx for invalid JSON, got %d", resp.StatusCode)
+	}
+
+	var prob map[string]interface{}
+	json.NewDecoder(resp.Body).Decode(&prob)
+
+	// Invalid JSON error should mention JSON parsing, not model
+	detail := prob["detail"].(string)
+	if !strings.Contains(strings.ToLower(detail), "json") {
+		t.Errorf("expected detail to mention JSON for invalid JSON error")
+	}
+}
+
+// TestUnknownModelDoesNotContactUpstream verifies no upstream call is made
+func TestUnknownModelDoesNotContactUpstream(t *testing.T) {
+	upstreamCalled := false
+	upstreamServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamCalled = true
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer upstreamServer.Close()
+
+	upstreamAddr := strings.TrimPrefix(upstreamServer.URL, "http://")
+
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: upstreamAddr,
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	_, _ = http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown","messages":[]}`)),
+	)
+
+	if upstreamCalled {
+		t.Errorf("upstream should not be called for unknown model")
+	}
+}
+
+// TestUnknownModelLogsReason verifies rejection is logged
+func TestUnknownModelLogsReason(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// This test verifies logging behavior by checking the handler's logger output
+	// In a real scenario, you'd capture stderr or use a test logger
+	_, _ = http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"gpt-4","messages":[]}`)),
+	)
+
+	// Logging is verified by checking that no panic occurs
+	// and the request completes successfully
+}
+
+// TestMissingModelAndUnknownModelBothReturn4xx verifies consistent error class
+func TestMissingModelAndUnknownModelBothReturn4xx(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	// Test missing model
+	resp1, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp1.Body.Close()
+
+	// Test unknown model
+	resp2, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown","messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp2.Body.Close()
+
+	// Both should be in 4xx range
+	if resp1.StatusCode < 400 || resp1.StatusCode >= 500 {
+		t.Errorf("expected 4xx for missing model, got %d", resp1.StatusCode)
+	}
+
+	if resp2.StatusCode < 400 || resp2.StatusCode >= 500 {
+		t.Errorf("expected 4xx for unknown model, got %d", resp2.StatusCode)
+	}
+
+	// Both should be problem+json
+	ct1 := resp1.Header.Get("Content-Type")
+	ct2 := resp2.Header.Get("Content-Type")
+
+	if !strings.Contains(ct1, "application/problem+json") {
+		t.Errorf("expected problem+json for missing model")
+	}
+
+	if !strings.Contains(ct2, "application/problem+json") {
+		t.Errorf("expected problem+json for unknown model")
+	}
+}
+
+// TestProblemDetailHasRequiredFields verifies RFC 9457 compliance
+func TestProblemDetailHasRequiredFields(t *testing.T) {
+	cfg := &config.Config{
+		Models: map[string]*config.ModelUpstream{
+			"reasoning": {
+				Name:    "reasoning",
+				Address: "reasoning-predictor:80",
+			},
+		},
+		Routes: make(map[string]*config.Route),
+	}
+
+	handler := New(cfg)
+	defer handler.Close()
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	resp, err := http.Post(
+		server.URL+"/v1/chat/completions",
+		"application/json",
+		bytes.NewReader([]byte(`{"model":"unknown","messages":[]}`)),
+	)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	var prob map[string]interface{}
+	json.NewDecoder(resp.Body).Decode(&prob)
+
+	// RFC 9457 required fields
+	if prob["type"] == nil {
+		t.Errorf("expected 'type' field in problem detail")
+	}
+
+	if prob["title"] == nil {
+		t.Errorf("expected 'title' field in problem detail")
+	}
+
+	if prob["status"] == nil {
+		t.Errorf("expected 'status' field in problem detail")
+	}
+
+	if prob["detail"] == nil {
+		t.Errorf("expected 'detail' field in problem detail")
+	}
+}

k8s/kustomization.yaml

@@ -17,7 +17,7 @@ resources:
 #   kustomize edit set image forgejo.riotpiao.com/rock/api-gateway=:<sha>
 images:
 - name: forgejo.riotpiao.com/rock/api-gateway
-  newTag: REPLACE_WITH_FIRST_BUILD_SHA
+  newTag: v0.0.0
 
 commonLabels:
   app: api-gateway

testdata/config/harness-with-models.yaml

@@ -0,0 +1,26 @@
+# Local development harness config with model registry for body-based dispatch.
+# This config is used for testing task 2.2 (body-based dispatch) and task 2.3 (error handling).
+# Every upstream points at the single stub server on loopback 127.0.0.1:9080.
+
+routes: []
+
+models:
+  - name: "reasoning"
+    address: "127.0.0.1:9080"
+    path: "/v1/chat/completions"
+  
+  - name: "ornith:35b"
+    address: "127.0.0.1:9080"
+    path: "/v1/chat/completions"
+  
+  - name: "qwen2.5:3b-instruct"
+    address: "127.0.0.1:9080"
+    path: "/v1/chat/completions"
+  
+  - name: "nomic-ai/nomic-embed-text-v2-moe"
+    address: "127.0.0.1:9080"
+    path: "/v1/embeddings"
+  
+  - name: "BAAI/bge-reranker-base"
+    address: "127.0.0.1:9080"
+    path: "/v1/rerank"