Normalize SDK errors for clients

openhands-sdk/openhands/sdk/agent/agent.py

@@ -169,8 +169,8 @@ def step(
             on_event(error_message)
             return
         except Exception as e:
-            # If there is a condenser registered and the exception is a context window
-            # exceeded, we can recover by triggering a condensation request.
+            # If condenser is available and error is context window exceeded, trigger
+            # condensation
             if (
                 self.condenser is not None
                 and self.condenser.handles_condensation_requests()
@@ -181,9 +181,11 @@ def step(
                 )
                 on_event(CondensationRequest())
                 return
-            # If the error isn't recoverable, keep propagating it up the stack.
-            else:
-                raise e
+            # Otherwise, map to SDK-typed errors and rethrow for clients
+            mapped = self.llm._map_exception(e)
+            if mapped is not e:
+                raise mapped from e
+            raise
 
         # LLMResponse already contains the converted message and metrics snapshot
         message: Message = llm_response.message

openhands-sdk/openhands/sdk/llm/exceptions/__init__.py

@@ -0,0 +1,45 @@
+from .classifier import is_context_window_exceeded, looks_like_auth_error
+from .mapping import map_provider_exception
+from .types import (
+    FunctionCallConversionError,
+    FunctionCallNotExistsError,
+    FunctionCallValidationError,
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMError,
+    LLMMalformedActionError,
+    LLMNoActionError,
+    LLMNoResponseError,
+    LLMRateLimitError,
+    LLMResponseError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+    OperationCancelled,
+    UserCancelledError,
+)
+
+
+__all__ = [
+    # Types
+    "LLMError",
+    "LLMMalformedActionError",
+    "LLMNoActionError",
+    "LLMResponseError",
+    "FunctionCallConversionError",
+    "FunctionCallValidationError",
+    "FunctionCallNotExistsError",
+    "LLMNoResponseError",
+    "LLMContextWindowExceedError",
+    "LLMAuthenticationError",
+    "LLMRateLimitError",
+    "LLMTimeoutError",
+    "LLMServiceUnavailableError",
+    "LLMBadRequestError",
+    "UserCancelledError",
+    "OperationCancelled",
+    # Helpers
+    "is_context_window_exceeded",
+    "looks_like_auth_error",
+    "map_provider_exception",
+]

openhands-sdk/openhands/sdk/llm/exceptions/classifier.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from litellm.exceptions import BadRequestError, ContextWindowExceededError, OpenAIError
+
+from .types import LLMContextWindowExceedError
+
+
+# Minimal, provider-agnostic context-window detection
+LONG_PROMPT_PATTERNS: list[str] = [
+    "contextwindowexceedederror",
+    "prompt is too long",
+    "input length and `max_tokens` exceed context limit",
+    "please reduce the length of",
+    "the request exceeds the available context size",
+    "context length exceeded",
+]
+
+
+def is_context_window_exceeded(exception: Exception) -> bool:
+    if isinstance(exception, (ContextWindowExceededError, LLMContextWindowExceedError)):
+        return True
+
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+
+    s = str(exception).lower()
+    return any(p in s for p in LONG_PROMPT_PATTERNS)
+
+
+AUTH_PATTERNS: list[str] = [
+    "invalid api key",
+    "unauthorized",
+    "missing api key",
+    "invalid authentication",
+    "access denied",
+]
+
+
+def looks_like_auth_error(exception: Exception) -> bool:
+    if not isinstance(exception, (BadRequestError, OpenAIError)):
+        return False
+    s = str(exception).lower()
+    if any(p in s for p in AUTH_PATTERNS):
+        return True
+    # Some providers include explicit status codes in message text
+    for code in ("status 401", "status 403"):
+        if code in s:
+            return True
+    return False

openhands-sdk/openhands/sdk/llm/exceptions/mapping.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from litellm.exceptions import (
+    APIConnectionError,
+    BadRequestError,
+    InternalServerError,
+    RateLimitError,
+    ServiceUnavailableError,
+    Timeout as LiteLLMTimeout,
+)
+
+from .classifier import is_context_window_exceeded, looks_like_auth_error
+from .types import (
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMRateLimitError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+)
+
+
+def map_provider_exception(exception: Exception) -> Exception:
+    """
+    Map provider/LiteLLM exceptions to SDK-typed exceptions.
+
+    Returns original exception if no mapping applies.
+    """
+    # Context window exceeded first (highest priority)
+    if is_context_window_exceeded(exception):
+        return LLMContextWindowExceedError(str(exception))
+
+    # Auth-like errors often appear as BadRequest/OpenAIError with specific text
+    if looks_like_auth_error(exception):
+        return LLMAuthenticationError(str(exception))
+
+    if isinstance(exception, RateLimitError):
+        return LLMRateLimitError(str(exception))
+
+    if isinstance(exception, LiteLLMTimeout):
+        return LLMTimeoutError(str(exception))
+
+    # Connectivity and service-side availability issues → service unavailable
+    if isinstance(
+        exception, (APIConnectionError, ServiceUnavailableError, InternalServerError)
+    ):
+        return LLMServiceUnavailableError(str(exception))
+
+    # Generic client-side 4xx errors
+    if isinstance(exception, BadRequestError):
+        return LLMBadRequestError(str(exception))
+
+    # Unknown: let caller re-raise original
+    return exception

openhands-sdk/openhands/sdk/llm/exceptions/types.py

@@ -0,0 +1,101 @@
+class LLMError(Exception):
+    message: str
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message
+
+
+# General response parsing/validation errors
+class LLMMalformedActionError(LLMError):
+    def __init__(self, message: str = "Malformed response") -> None:
+        super().__init__(message)
+
+
+class LLMNoActionError(LLMError):
+    def __init__(self, message: str = "Agent must return an action") -> None:
+        super().__init__(message)
+
+
+class LLMResponseError(LLMError):
+    def __init__(
+        self, message: str = "Failed to retrieve action from LLM response"
+    ) -> None:
+        super().__init__(message)
+
+
+# Function-calling conversion/validation
+class FunctionCallConversionError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallValidationError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class FunctionCallNotExistsError(LLMError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+# Provider/transport related
+class LLMNoResponseError(LLMError):
+    def __init__(
+        self,
+        message: str = (
+            "LLM did not return a response. This is only seen in Gemini models so far."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class LLMContextWindowExceedError(LLMError):
+    def __init__(
+        self,
+        message: str = (
+            "Conversation history longer than LLM context window limit. "
+            "Consider enabling a condenser or shortening inputs."
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class LLMAuthenticationError(LLMError):
+    def __init__(self, message: str = "Invalid or missing API credentials") -> None:
+        super().__init__(message)
+
+
+class LLMRateLimitError(LLMError):
+    def __init__(self, message: str = "Rate limit exceeded") -> None:
+        super().__init__(message)
+
+
+class LLMTimeoutError(LLMError):
+    def __init__(self, message: str = "LLM request timed out") -> None:
+        super().__init__(message)
+
+
+class LLMServiceUnavailableError(LLMError):
+    def __init__(self, message: str = "LLM service unavailable") -> None:
+        super().__init__(message)
+
+
+class LLMBadRequestError(LLMError):
+    def __init__(self, message: str = "Bad request to LLM provider") -> None:
+        super().__init__(message)
+
+
+# Other
+class UserCancelledError(Exception):
+    def __init__(self, message: str = "User cancelled the request") -> None:
+        super().__init__(message)
+
+
+class OperationCancelled(Exception):
+    def __init__(self, message: str = "Operation was cancelled") -> None:
+        super().__init__(message)