Normalize SDK errors for clients (#980)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: enyst

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

@@ -28,7 +28,10 @@
     TextContent,
     ThinkingBlock,
 )
-from openhands.sdk.llm.exceptions import FunctionCallValidationError
+from openhands.sdk.llm.exceptions import (
+    FunctionCallValidationError,
+    LLMContextWindowExceedError,
+)
 from openhands.sdk.logger import get_logger
 from openhands.sdk.security.confirmation_policy import NeverConfirm
 from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer
@@ -168,22 +171,19 @@ 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.
+        except LLMContextWindowExceedError:
+            # If condenser is available and handles requests, trigger condensation
             if (
                 self.condenser is not None
                 and self.condenser.handles_condensation_requests()
-                and self.llm.is_context_window_exceeded_exception(e)
             ):
                 logger.warning(
                     "LLM raised context window exceeded error, triggering condensation"
                 )
                 on_event(CondensationRequest())
                 return
-            # If the error isn't recoverable, keep propagating it up the stack.
-            else:
-                raise e
+            # No condenser available; re-raise for client handling
+            raise
 
         # LLMResponse already contains the converted message and metrics snapshot
         message: Message = llm_response.message

openhands-sdk/openhands/sdk/llm/exceptions.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/__init__.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/classifier.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