Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(server): map HTTP status for error-envelope return sites in stats/debug/sessions (#3722)

euyua9750390b0cf4a
diff --git a/openviking/server/models.py b/openviking/server/models.py
index ad2ca5607..67c08cf53 100644
--- a/openviking/server/models.py
+++ b/openviking/server/models.py
@@ -58,5 +58,8 @@ ERROR_CODE_TO_HTTP_STATUS = {
"WRITE_FAILED": 500,
"REFRESH_FAILED": 500,
"BOT_RESTARTED": 503,
+ "INTERNAL_ERROR": 500,
+ "NO_VECTOR_DB": 503,
+ "INVALID_FILTER": 400,
"UNKNOWN": 500,
}
diff --git a/openviking/server/routers/debug.py b/openviking/server/routers/debug.py
index 71cb34fcb..dad71b7e5 100644
--- a/openviking/server/routers/debug.py
+++ b/openviking/server/routers/debug.py
@@ -17,6 +17,7 @@ from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.models import ErrorInfo, Response
+from openviking.server.responses import error_response
from openviking.storage.vikingdb_manager import VikingDBManagerProxy
router = APIRouter(prefix="/api/v1/debug", tags=["debug"])
@@ -42,9 +43,8 @@ async def debug_vector_scroll(
"""Get paginated vector records with tenant isolation."""
service = get_service()
if not service.vikingdb_manager:
- return Response(
- status="error",
- error=ErrorInfo(code="NO_VECTOR_DB", message="Vector DB not initialized"),
+ return error_response(
+ code="NO_VECTOR_DB", message="Vector DB not initialized"
)
proxy = VikingDBManagerProxy(service.vikingdb_manager, _ctx)
@@ -71,9 +71,8 @@ async def debug_vector_count(
service = get_service()
if not service.vikingdb_manager:
- return Response(
- status="error",
- error=ErrorInfo(code="NO_VECTOR_DB", message="Vector DB not initialized"),
+ return error_response(
+ code="NO_VECTOR_DB", message="Vector DB not initialized"
)
proxy = VikingDBManagerProxy(service.vikingdb_manager, _ctx)
@@ -83,9 +82,8 @@ async def debug_vector_count(
try:
filter_expr = json.loads(filter)
except json.JSONDecodeError:
- return Response(
- status="error",
- error=ErrorInfo(code="INVALID_FILTER", message="Invalid filter JSON"),
+ return error_response(
+ code="INVALID_FILTER", message="Invalid filter JSON"
)
if uri:
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index a0bee9774..f88e9c7c0 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -373,9 +373,8 @@ async def get_session_archive(
try:
result = await session.get_session_archive(archive_id)
except NotFoundError:
- return Response(
- status="error",
- error=ErrorInfo(code="NOT_FOUND", message=f"Archive {archive_id} not found"),
+ return error_response(
+ code="NOT_FOUND", message=f"Archive {archive_id} not found"
)
return Response(status="ok", result=_to_jsonable(result))
diff --git a/openviking/server/routers/stats.py b/openviking/server/routers/stats.py
index e76d50e44..2f788f69d 100644
--- a/openviking/server/routers/stats.py
+++ b/openviking/server/routers/stats.py
@@ -10,6 +10,7 @@ from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.models import ErrorInfo, Response
+from openviking.server.responses import error_response
from openviking.storage.stats_aggregator import MEMORY_CATEGORIES, StatsAggregator
from openviking_cli.utils import get_logger
@@ -37,12 +38,9 @@ async def get_memory_stats(
Optionally filter by a single category.
"""
if category and category not in MEMORY_CATEGORIES:
- return Response(
- status="error",
- error=ErrorInfo(
- code="INVALID_ARGUMENT",
- message=f"Unknown category: {category}. Valid categories: {', '.join(MEMORY_CATEGORIES)}",
- ),
+ return error_response(
+ code="INVALID_ARGUMENT",
+ message=f"Unknown category: {category}. Valid categories: {', '.join(MEMORY_CATEGORIES)}",
)
aggregator = _get_aggregator()
@@ -62,19 +60,12 @@ async def get_session_stats(
result = await aggregator.get_session_extraction_stats(session_id, service, _ctx)
return Response(status="ok", result=result)
except KeyError:
- return Response(
- status="error",
- error=ErrorInfo(
- code="NOT_FOUND",
- message=f"Session not found: {session_id}",
- ),
+ return error_response(
+ code="NOT_FOUND", message=f"Session not found: {session_id}"
)
except Exception as e:
logger.error("Failed to get session stats for %s: %s", session_id, e)
- return Response(
- status="error",
- error=ErrorInfo(
- code="INTERNAL_ERROR",
- message=f"Failed to retrieve session stats: {type(e).__name__}",
- ),
+ return error_response(
+ code="INTERNAL_ERROR",
+ message=f"Failed to retrieve session stats: {type(e).__name__}",
)
diff --git a/tests/server/test_error_envelope_status_codes.py b/tests/server/test_error_envelope_status_codes.py
new file mode 100644
index 000000000..38a8f6452
--- /dev/null
+++ b/tests/server/test_error_envelope_status_codes.py
@@ -0,0 +1,104 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Regression tests: error-envelope return sites must surface mapped HTTP status codes.
+
+These routers historically returned ``Response(status="error", error=ErrorInfo(...))``
+directly, which FastAPI shipped with HTTP 200 because there was no ``status_code``
+override. The fix routes them through ``error_response(...)`` so the canonical
+``ERROR_CODE_TO_HTTP_STATUS`` mapping drives the HTTP status.
+
+Each test pairs the route with the documented ``ErrorInfo`` code, so a future
+refactor that drops an entry from the map or forgets to use ``error_response()``
+will fail loudly here.
+"""
+
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+
+def _assert_envelope(resp: httpx.Response, expected_code: int, expected_error_code: str):
+ assert resp.status_code == expected_code, (
+ f"expected HTTP {expected_code} for {expected_error_code}, got {resp.status_code}: {resp.text}"
+ )
+ body = resp.json()
+ assert body["status"] == "error", body
+ assert body["error"]["code"] == expected_error_code, body
+ assert body["error"]["message"], body
+ return body
+
+
+async def test_stats_memories_unknown_category_returns_400(client: httpx.AsyncClient):
+ resp = await client.get("/api/v1/stats/memories", params={"category": "not_a_real_category"})
+ _assert_envelope(resp, expected_code=400, expected_error_code="INVALID_ARGUMENT")
+
+
+async def test_stats_session_not_found_returns_404(client: httpx.AsyncClient):
+ resp = await client.get("/api/v1/stats/sessions/session-does-not-exist")
+ _assert_envelope(resp, expected_code=404, expected_error_code="NOT_FOUND")
+
+
+async def test_stats_session_internal_error_returns_500(client: httpx.AsyncClient):
+ """When the aggregator raises an unexpected exception, the route must
+ return 500 with the canonical INTERNAL_ERROR envelope, not HTTP 200."""
+ with patch(
+ "openviking.server.routers.stats._get_aggregator"
+ ) as fake_agg:
+ agg = fake_agg.return_value
+ agg.get_session_extraction_stats.side_effect = RuntimeError("boom")
+ resp = await client.get("/api/v1/stats/sessions/anything")
+ _assert_envelope(resp, expected_code=500, expected_error_code="INTERNAL_ERROR")
+
+
+async def test_debug_vector_scroll_no_vikingdb_returns_503(client: httpx.AsyncClient):
+ with patch(
+ "openviking.server.dependencies.get_service"
+ ) as fake_get_service:
+ service = fake_get_service.return_value
+ service.vikingdb_manager = None
+ resp = await client.get("/api/v1/debug/vector/scroll")
+ _assert_envelope(resp, expected_code=503, expected_error_code="NO_VECTOR_DB")
+
+
+async def test_debug_vector_count_no_vikingdb_returns_503(client: httpx.AsyncClient):
+ with patch(
+ "openviking.server.dependencies.get_service"
+ ) as fake_get_service:
+ service = fake_get_service.return_value
+ service.vikingdb_manager = None
+ resp = await client.get("/api/v1/debug/vector/count")
+ _assert_envelope(resp, expected_code=503, expected_error_code="NO_VECTOR_DB")
+
+
+async def test_debug_vector_count_invalid_filter_returns_400(client: httpx.AsyncClient):
+ """Bad JSON in the ``filter`` query string must surface as 400, not 200."""
+ with patch(
+ "openviking.server.dependencies.get_service"
+ ) as fake_get_service:
+ service = fake_get_service.return_value
+ service.vikingdb_manager = object() # truthy so we get past the NO_VECTOR_DB guard
+ resp = await client.get(
+ "/api/v1/debug/vector/count", params={"filter": "not-json{"}
+ )
+ _assert_envelope(resp, expected_code=400, expected_error_code="INVALID_FILTER")
+
+
+async def test_sessions_archive_not_found_returns_404(client: httpx.AsyncClient):
+ """Archive lookups for an unknown archive id must return 404, not 200."""
+ create_resp = await client.post("/api/v1/sessions", json={})
+ assert create_resp.status_code == 200
+ session_id = create_resp.json()["result"]["session_id"]
+
+ resp = await client.get(f"/api/v1/sessions/{session_id}/archives/no-such-archive")
+ _assert_envelope(resp, expected_code=404, expected_error_code="NOT_FOUND")
+
+
+def test_error_code_map_has_internal_error_no_vector_db_invalid_filter():
+ """Guards the status map: dropping any of these codes re-introduces the bug
+ by silently falling back to HTTP 500 on routes that target them."""
+ from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS
+
+ assert ERROR_CODE_TO_HTTP_STATUS["INTERNAL_ERROR"] == 500
+ assert ERROR_CODE_TO_HTTP_STATUS["NO_VECTOR_DB"] == 503
+ assert ERROR_CODE_TO_HTTP_STATUS["INVALID_FILTER"] == 400