Skip to content

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

fix(model): map upstream provider errors (#1732)

Qin Haojie14b83736f8b3
diff --git a/openviking/server/error_mapping.py b/openviking/server/error_mapping.py
index e9ca3c714..f024abe7e 100644
--- a/openviking/server/error_mapping.py
+++ b/openviking/server/error_mapping.py
@@ -1,6 +1,10 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
+import ast
+import re
+from typing import Any, Iterator
+
from openviking.pyagfs.exceptions import (
AGFSClientError,
AGFSConnectionError,
@@ -19,6 +23,345 @@ from openviking_cli.exceptions import (
UnavailableError,
)
+_UPSTREAM_HTTP_STATUS_TO_ERROR_CODE = {
+ 400: "INVALID_ARGUMENT",
+ 401: "UNAUTHENTICATED",
+ 402: "RESOURCE_EXHAUSTED",
+ 403: "PERMISSION_DENIED",
+ 404: "NOT_FOUND",
+ 408: "DEADLINE_EXCEEDED",
+ 409: "CONFLICT",
+ 422: "INVALID_ARGUMENT",
+ 429: "RESOURCE_EXHAUSTED",
+ 500: "UNAVAILABLE",
+ 502: "UNAVAILABLE",
+ 503: "UNAVAILABLE",
+ 504: "DEADLINE_EXCEEDED",
+}
+
+_KNOWN_HTTP_STATUS_CODES = frozenset(_UPSTREAM_HTTP_STATUS_TO_ERROR_CODE)
+_UPSTREAM_ERROR_MARKERS = (
+ "api error",
+ "apierror",
+ "badrequesterror",
+ "authenticationerror",
+ "permissiondeniederror",
+ "ratelimiterror",
+ "httpstatuserror",
+ "openai",
+ "litellm",
+ "volcengine",
+ "ark",
+ "gemini",
+ "jina",
+ "voyage",
+ "cohere",
+ "dashscope",
+ "minimax",
+ "embedding",
+ "embedder",
+ "vlm",
+ "model",
+ "upstream",
+ "invalid api key",
+ "unauthorized",
+ "forbidden",
+ "too many requests",
+ "rate limit",
+ "quota",
+ "accountoverdue",
+)
+_API_KEY_CONFIG_MARKERS = (
+ "vlm configuration",
+ "embedding",
+ "embedder",
+ "provider",
+ "openai",
+ "azure",
+ "volcengine",
+ "jina",
+ "gemini",
+ "voyage",
+ "dashscope",
+ "minimax",
+ "cohere",
+)
+_HTTP_STATUS_PATTERNS = (
+ re.compile(r"\bHTTP\s*(\d{3})\b", re.IGNORECASE),
+ re.compile(r"\bstatus(?:\s+code)?\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
+ re.compile(r"\berror\s+code\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
+)
+
+
+def _iter_exception_chain(exc: Exception) -> Iterator[BaseException]:
+ seen: set[int] = set()
+ pending: list[BaseException] = [exc]
+ while pending:
+ current = pending.pop(0)
+ ident = id(current)
+ if ident in seen:
+ continue
+ seen.add(ident)
+ yield current
+ for nested in (getattr(current, "__cause__", None), getattr(current, "__context__", None)):
+ if isinstance(nested, BaseException) and id(nested) not in seen:
+ pending.append(nested)
+
+
+def _coerce_http_status(value: Any) -> int | None:
+ if isinstance(value, bool) or value is None:
+ return None
+ try:
+ status = int(value)
+ except (TypeError, ValueError):
+ return None
+ if 100 <= status <= 599:
+ return status
+ return None
+
+
+def _normalize_message(message: str) -> str:
+ return " ".join(str(message).split())
+
+
+def _dedupe_messages(messages: list[str]) -> list[str]:
+ result: list[str] = []
+ for message in messages:
+ normalized = _normalize_message(message)
+ if not normalized:
+ continue
+ if any(normalized == existing or normalized in existing for existing in result):
+ continue
+ result = [existing for existing in result if existing not in normalized]
+ result.append(normalized)
+ return result
+
+
+def _exception_chain_text(exc: Exception) -> str:
+ return "\n".join(_dedupe_messages([str(item) for item in _iter_exception_chain(exc)]))
+
+
+def _trim_message(message: str, limit: int = 500) -> str:
+ normalized = _normalize_message(message)
+ if len(normalized) <= limit:
+ return normalized
+ return normalized[: limit - 3] + "..."
+
+
+def _iter_braced_segments(text: str) -> Iterator[str]:
+ start: int | None = None
+ depth = 0
+ quote: str | None = None
+ escaped = False
+ for index, char in enumerate(text):
+ if quote is not None:
+ if escaped:
+ escaped = False
+ elif char == "\\":
+ escaped = True
+ elif char == quote:
+ quote = None
+ continue
+ if char in {'"', "'"}:
+ quote = char
+ elif char == "{":
+ if depth == 0:
+ start = index
+ depth += 1
+ elif char == "}" and depth:
+ depth -= 1
+ if depth == 0 and start is not None:
+ yield text[start : index + 1]
+ start = None
+
+
+def _extract_payload_message(payload: Any) -> str | None:
+ if not isinstance(payload, dict):
+ return None
+ error = payload.get("error")
+ if isinstance(error, dict):
+ message = error.get("message")
+ if isinstance(message, str) and message.strip():
+ return message.strip()
+ message = payload.get("message")
+ if isinstance(message, str) and message.strip():
+ return message.strip()
+ return None
+
+
+def _extract_provider_error_message(text: str) -> str | None:
+ for segment in _iter_braced_segments(text):
+ try:
+ payload = ast.literal_eval(segment)
+ except (SyntaxError, ValueError):
+ continue
+ message = _extract_payload_message(payload)
+ if message:
+ return message
+ return None
+
+
+def _upstream_detail_message(exc: Exception) -> str:
+ text = _exception_chain_text(exc)
+ return _extract_provider_error_message(text) or text
+
+
+def _looks_like_upstream_model_error(exc: Exception) -> bool:
+ text = _exception_chain_text(exc).lower()
+ return any(marker in text for marker in _UPSTREAM_ERROR_MARKERS)
+
+
+def _is_model_api_key_configuration_error(exc: Exception) -> bool:
+ text = _exception_chain_text(exc).lower()
+ if "api_key" not in text and "api key" not in text:
+ return False
+ if "invalid api key" in text or "unauthorized" in text:
+ return False
+ missing_key_phrases = (
+ "requires 'api_key'",
+ "requires api_key",
+ "api_key is required",
+ "api key is required",
+ "requires 'api key'",
+ )
+ if not any(phrase in text for phrase in missing_key_phrases):
+ return False
+ if any(marker in text for marker in _API_KEY_CONFIG_MARKERS):
+ return True
+ return text.strip() in (
+ "api_key is required",
+ "api key is required",
+ )
+
+
+def _extract_structured_http_status(
+ exc: Exception,
+) -> tuple[int, BaseException] | tuple[None, None]:
+ for item in _iter_exception_chain(exc):
+ for attr in ("status_code", "http_status", "status"):
+ status = _coerce_http_status(getattr(item, attr, None))
+ if status is not None:
+ return status, item
+ code = getattr(item, "code", None)
+ if not isinstance(code, str):
+ status = _coerce_http_status(code)
+ if status is not None:
+ return status, item
+ response = getattr(item, "response", None)
+ if response is not None:
+ for attr in ("status_code", "status"):
+ status = _coerce_http_status(getattr(response, attr, None))
+ if status is not None:
+ return status, item
+ return None, None
+
+
+def _extract_text_http_status(exc: Exception) -> int | None:
+ if not _looks_like_upstream_model_error(exc):
+ return None
+ text = _exception_chain_text(exc)
+ for pattern in _HTTP_STATUS_PATTERNS:
+ match = pattern.search(text)
+ if match:
+ status = _coerce_http_status(match.group(1))
+ if status is not None:
+ return status
+ for status in _KNOWN_HTTP_STATUS_CODES:
+ if re.search(rf"\b{status}\b", text):
+ return status
+ return None
+
+
+def _upstream_code_for_status(status: int) -> str:
+ if status in _UPSTREAM_HTTP_STATUS_TO_ERROR_CODE:
+ return _UPSTREAM_HTTP_STATUS_TO_ERROR_CODE[status]
+ if 400 <= status < 500:
+ return "INVALID_ARGUMENT"
+ if 500 <= status < 600:
+ return "UNAVAILABLE"
+ return "UNKNOWN"
+
+
+def _build_upstream_error(
+ *,
+ code: str,
+ message: str,
+ status: int | None = None,
+ source: BaseException | None = None,
+) -> OpenVikingError:
+ labels = {
+ "INVALID_ARGUMENT": "Upstream model request was rejected",
+ "UNAUTHENTICATED": "Upstream model authentication failed",
+ "PERMISSION_DENIED": "Upstream model permission denied",
+ "NOT_FOUND": "Upstream model resource not found",
+ "CONFLICT": "Upstream model request conflicted",
+ "RESOURCE_EXHAUSTED": "Upstream model quota or rate limit exceeded",
+ "DEADLINE_EXCEEDED": "Upstream model request timed out",
+ "UNAVAILABLE": "Upstream model service unavailable",
+ }
+ detail_message = _trim_message(message)
+ display = labels.get(code, "Upstream model error")
+ if status is not None:
+ display = f"{display} (HTTP {status})"
+ if detail_message:
+ display = f"{display}: {detail_message}"
+ details: dict[str, Any] = {"upstream_message": detail_message}
+ if status is not None:
+ details["upstream_status_code"] = status
+ if source is not None:
+ details["upstream_error_type"] = type(source).__name__
+ return OpenVikingError(display, code=code, details=details)
+
+
+def _map_upstream_api_error(exc: Exception) -> OpenVikingError | None:
+ if _is_model_api_key_configuration_error(exc):
+ return FailedPreconditionError(
+ "Model provider API key is not configured",
+ details={"reason": _trim_message(_exception_chain_text(exc))},
+ )
+
+ status, source = _extract_structured_http_status(exc)
+ if status is None:
+ status = _extract_text_http_status(exc)
+ if status is not None:
+ code = _upstream_code_for_status(status)
+ if code == "UNKNOWN":
+ return None
+ return _build_upstream_error(
+ code=code,
+ status=status,
+ source=source,
+ message=_upstream_detail_message(exc),
+ )
+
+ if not _looks_like_upstream_model_error(exc):
+ return None
+ text = _exception_chain_text(exc)
+ lowered = text.lower()
+ if "invalid api key" in lowered or "unauthorized" in lowered:
+ return _build_upstream_error(
+ code="UNAUTHENTICATED", message=_upstream_detail_message(exc), source=exc
+ )
+ if "forbidden" in lowered:
+ return _build_upstream_error(
+ code="PERMISSION_DENIED", message=_upstream_detail_message(exc), source=exc
+ )
+ if any(
+ marker in lowered
+ for marker in (
+ "too many requests",
+ "rate limit",
+ "ratelimit",
+ "quota",
+ "accountoverdue",
+ "resource exhausted",
+ )
+ ):
+ return _build_upstream_error(
+ code="RESOURCE_EXHAUSTED", message=_upstream_detail_message(exc), source=exc
+ )
+ return None
+
def is_not_found_error(exc: Exception) -> bool:
if isinstance(exc, FileNotFoundError):
@@ -62,6 +405,11 @@ def map_exception(
return PermissionDeniedError(str(exc), resource=resource)
if isinstance(exc, FileNotFoundError):
return NotFoundError(resource or str(exc), resource_type)
+ if _is_model_api_key_configuration_error(exc):
+ return FailedPreconditionError(
+ "Model provider API key is not configured",
+ details={"reason": _trim_message(_exception_chain_text(exc))},
+ )
if isinstance(exc, ValueError):
message = str(exc)
if is_invalid_uri_error(exc):
@@ -98,6 +446,9 @@ def map_exception(
return ConflictError(message, resource=resource)
if "timeout" in lowered or "connection refused" in lowered:
return UnavailableError("storage backend", reason=message)
+ upstream_mapped = _map_upstream_api_error(exc)
+ if upstream_mapped is not None:
+ return upstream_mapped
message = str(exc)
lowered = message.lower()
if is_not_found_error(exc):
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index 97652993e..e7d708930 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -16,7 +16,9 @@ import httpx
from openviking.telemetry import TelemetryRequest, normalize_telemetry_request
from openviking_cli.client.base import BaseClient
from openviking_cli.exceptions import (
+ AbortedError,
AlreadyExistsError,
+ ConflictError,
DeadlineExceededError,
EmbeddingFailedError,
FailedPreconditionError,
@@ -28,9 +30,11 @@ from openviking_cli.exceptions import (
OpenVikingError,
PermissionDeniedError,
ProcessingError,
+ ResourceExhaustedError,
SessionExpiredError,
UnauthenticatedError,
UnavailableError,
+ UnimplementedError,
VLMFailedError,
)
from openviking_cli.retrieve.types import FindResult
@@ -45,17 +49,22 @@ ERROR_CODE_TO_EXCEPTION = {
"INVALID_URI": InvalidURIError,
"NOT_FOUND": NotFoundError,
"ALREADY_EXISTS": AlreadyExistsError,
+ "CONFLICT": ConflictError,
"FAILED_PRECONDITION": FailedPreconditionError,
+ "ABORTED": AbortedError,
"UNAUTHENTICATED": UnauthenticatedError,
"PERMISSION_DENIED": PermissionDeniedError,
+ "RESOURCE_EXHAUSTED": ResourceExhaustedError,
"UNAVAILABLE": UnavailableError,
"INTERNAL": InternalError,
"DEADLINE_EXCEEDED": DeadlineExceededError,
+ "UNIMPLEMENTED": UnimplementedError,
"NOT_INITIALIZED": NotInitializedError,
"PROCESSING_ERROR": ProcessingError,
"EMBEDDING_FAILED": EmbeddingFailedError,
"VLM_FAILED": VLMFailedError,
"SESSION_EXPIRED": SessionExpiredError,
+ "UNKNOWN": OpenVikingError,
}
@@ -275,7 +284,15 @@ class AsyncHTTPClient(BaseClient):
exc_class = ERROR_CODE_TO_EXCEPTION.get(code, OpenVikingError)
# Handle different exception constructors
- if exc_class in (InvalidArgumentError,):
+ if exc_class == OpenVikingError:
+ raise exc_class(message, code=code, details=details)
+ elif exc_class in (
+ InvalidArgumentError,
+ FailedPreconditionError,
+ ResourceExhaustedError,
+ AbortedError,
+ UnimplementedError,
+ ):
raise exc_class(message, details=details)
elif exc_class == InvalidURIError:
uri = details.get("uri", "") if details else ""
diff --git a/openviking_cli/exceptions.py b/openviking_cli/exceptions.py
index 9205cb6fc..875e3acb0 100644
--- a/openviking_cli/exceptions.py
+++ b/openviking_cli/exceptions.py
@@ -86,6 +86,13 @@ class FailedPreconditionError(OpenVikingError):
super().__init__(message, code="FAILED_PRECONDITION", details=details)
+class AbortedError(OpenVikingError):
+ """Operation was aborted, typically due to a concurrency conflict."""
+
+ def __init__(self, message: str = "Operation aborted", details: Optional[dict] = None):
+ super().__init__(message, code="ABORTED", details=details)
+
+
# ============= Authentication Errors =============
@@ -119,6 +126,13 @@ class UnavailableError(OpenVikingError):
)
+class ResourceExhaustedError(OpenVikingError):
+ """Resource quota, rate limit, or billing capacity was exhausted."""
+
+ def __init__(self, message: str = "Resource exhausted", details: Optional[dict] = None):
+ super().__init__(message, code="RESOURCE_EXHAUSTED", details=details)
+
+
class InternalError(OpenVikingError):
"""Internal server error."""
@@ -139,6 +153,13 @@ class DeadlineExceededError(OpenVikingError):
)
+class UnimplementedError(OpenVikingError):
+ """Operation is not implemented."""
+
+ def __init__(self, message: str = "Operation not implemented", details: Optional[dict] = None):
+ super().__init__(message, code="UNIMPLEMENTED", details=details)
+
+
# ============= Business Errors =============
diff --git a/tests/client/test_http_error_mapping.py b/tests/client/test_http_error_mapping.py
new file mode 100644
index 000000000..81feb84c0
--- /dev/null
+++ b/tests/client/test_http_error_mapping.py
@@ -0,0 +1,65 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Focused tests for SDK HTTP error-code mapping."""
+
+import pytest
+
+from openviking_cli.client.http import AsyncHTTPClient
+from openviking_cli.exceptions import (
+ AbortedError,
+ ConflictError,
+ OpenVikingError,
+ ResourceExhaustedError,
+ UnimplementedError,
+)
+
+
+ ("code", "exc_type"),
+ (
+ ("CONFLICT", ConflictError),
+ ("ABORTED", AbortedError),
+ ("RESOURCE_EXHAUSTED", ResourceExhaustedError),
+ ("UNIMPLEMENTED", UnimplementedError),
+ ),
+)
+def test_client_maps_standard_error_codes(code, exc_type):
+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")
+
+ with pytest.raises(exc_type) as exc_info:
+ client._raise_exception({"code": code, "message": "mapped"})
+
+ assert exc_info.value.code == code
+
+
+def test_client_maps_resource_exhausted_error_code():
+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")
+
+ with pytest.raises(ResourceExhaustedError) as exc_info:
+ client._raise_exception(
+ {
+ "code": "RESOURCE_EXHAUSTED",
+ "message": "Upstream model quota or rate limit exceeded",
+ "details": {"upstream_status_code": 429},
+ }
+ )
+
+ assert exc_info.value.code == "RESOURCE_EXHAUSTED"
+ assert exc_info.value.details == {"upstream_status_code": 429}
+
+
+def test_client_preserves_unknown_error_code():
+ client = AsyncHTTPClient(url="http://127.0.0.1:1933")
+
+ with pytest.raises(OpenVikingError) as exc_info:
+ client._raise_exception(
+ {
+ "code": "PROVIDER_SPECIFIC",
+ "message": "provider-specific failure",
+ "details": {"x": 1},
+ }
+ )
+
+ assert exc_info.value.code == "PROVIDER_SPECIFIC"
+ assert exc_info.value.details == {"x": 1}
diff --git a/tests/server/test_error_mapping.py b/tests/server/test_error_mapping.py
index f8de4031e..d6419d34b 100644
--- a/tests/server/test_error_mapping.py
+++ b/tests/server/test_error_mapping.py
@@ -3,9 +3,26 @@
"""Focused tests for HTTP server exception-to-error mapping."""
-from openviking.pyagfs.exceptions import AGFSClientError
+from openviking.pyagfs.exceptions import AGFSClientError, AGFSHTTPError
from openviking.server.error_mapping import map_exception
-from openviking_cli.exceptions import InvalidURIError, NotFoundError
+from openviking_cli.exceptions import FailedPreconditionError, InvalidURIError, NotFoundError
+
+
+class _UpstreamHTTPError(Exception):
+ def __init__(self, status_code: int, message: str):
+ super().__init__(message)
+ self.status_code = status_code
+
+
+class _Response:
+ def __init__(self, status_code: int):
+ self.status_code = status_code
+
+
+class _HTTPStatusError(Exception):
+ def __init__(self, status_code: int, message: str):
+ super().__init__(message)
+ self.response = _Response(status_code)
def test_agfs_client_does_not_exist_maps_to_not_found():
@@ -31,8 +48,94 @@ def test_agfs_client_invalid_uri_maps_to_invalid_uri():
assert mapped.details["uri"] == "viking://"
+def test_agfs_http_status_keeps_storage_mapping():
+ mapped = map_exception(
+ AGFSHTTPError("No such file or directory", 404),
+ resource="viking://missing",
+ resource_type="file",
+ )
+
+ assert isinstance(mapped, NotFoundError)
+ assert mapped.code == "NOT_FOUND"
+ assert mapped.message == "File not found: viking://missing"
+
+
def test_value_error_invalid_uri_maps_to_invalid_uri():
mapped = map_exception(ValueError("invalid viking URI: missing path"), resource="viking://")
assert isinstance(mapped, InvalidURIError)
assert mapped.code == "INVALID_URI"
+
+
+def test_wrapped_upstream_401_maps_to_unauthenticated():
+ try:
+ raise RuntimeError("OpenAI VLM completion failed") from _UpstreamHTTPError(
+ 401, "invalid_api_key"
+ )
+ except RuntimeError as exc:
+ mapped = map_exception(exc)
+
+ assert mapped is not None
+ assert mapped.code == "UNAUTHENTICATED"
+ assert mapped.details["upstream_status_code"] == 401
+
+
+def test_upstream_provider_payload_message_is_not_duplicated():
+ provider_error = (
+ "Error code: 401 - {'error': {'code': 'AuthenticationError', "
+ "'message': \"The API key doesn\\'t exist. Request id: req-1\", "
+ "'param': '', 'type': 'Unauthorized'}}, request_id: req-1"
+ )
+ try:
+ raise RuntimeError(f"Volcengine embedding failed: {provider_error}") from (
+ _UpstreamHTTPError(401, provider_error)
+ )
+ except RuntimeError as exc:
+ mapped = map_exception(exc)
+
+ assert mapped is not None
+ assert mapped.code == "UNAUTHENTICATED"
+ assert mapped.message == (
+ "Upstream model authentication failed (HTTP 401): "
+ "The API key doesn't exist. Request id: req-1"
+ )
+ assert mapped.message.count("The API key doesn't exist") == 1
+ assert "Error code: 401" not in mapped.message
+
+
+def test_upstream_response_429_maps_to_resource_exhausted():
+ mapped = map_exception(_HTTPStatusError(429, "LiteLLM embedding failed: Too Many Requests"))
+
+ assert mapped is not None
+ assert mapped.code == "RESOURCE_EXHAUSTED"
+ assert mapped.details["upstream_status_code"] == 429
+
+
+def test_upstream_text_status_maps_to_permission_denied():
+ mapped = map_exception(RuntimeError("Cohere API error: 403 Forbidden"))
+
+ assert mapped is not None
+ assert mapped.code == "PERMISSION_DENIED"
+ assert mapped.details["upstream_status_code"] == 403
+
+
+def test_upstream_502_maps_to_unavailable():
+ mapped = map_exception(RuntimeError("Volcengine embedding failed: HTTP 502 Bad Gateway"))
+
+ assert mapped is not None
+ assert mapped.code == "UNAVAILABLE"
+ assert mapped.details["upstream_status_code"] == 502
+
+
+def test_model_api_key_configuration_error_maps_to_failed_precondition():
+ mapped = map_exception(ValueError("VLM configuration requires 'api_key' to be set"))
+
+ assert isinstance(mapped, FailedPreconditionError)
+ assert mapped.code == "FAILED_PRECONDITION"
+
+
+def test_bare_model_api_key_required_maps_to_failed_precondition():
+ mapped = map_exception(ValueError("api_key is required"))
+
+ assert isinstance(mapped, FailedPreconditionError)
+ assert mapped.code == "FAILED_PRECONDITION"