Exception Handling

Provider‑agnostic exceptions raised by the SDK and recommended patterns for handling them.

The SDK normalizes common provider errors into typed, provider‑agnostic exceptions so your application can handle them consistently across OpenAI, Anthropic, Groq, Google, and others.

This guide explains when these errors occur and shows recommended handling patterns for both direct LLM usage and higher‑level agent/conversation flows.

​

Why typed exceptions?

LLM providers format errors differently (status codes, messages, exception classes). The SDK maps those into stable types so client apps don’t depend on provider‑specific details. Typical benefits:

• One code path to handle auth, rate limits, timeouts, service issues, and bad requests
• Clear behavior when conversation history exceeds the context window
• Backward compatibility when you switch providers or SDK versions

​

Quick start: Using agents and conversations

Agent-driven conversations are the common entry point. Exceptions from the underlying LLM calls bubble up from conversation.run() and conversation.send_message(...) when a condenser is not configured.

from pydantic import SecretStr
from openhands.sdk import Agent, Conversation, LLM
from openhands.sdk.llm.exceptions import (
    LLMError,
    LLMAuthenticationError,
    LLMRateLimitError,
    LLMTimeoutError,
    LLMServiceUnavailableError,
    LLMBadRequestError,
    LLMContextWindowExceedError,
)

llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("your-key"))
agent = Agent(llm=llm, tools=[])
conversation = Conversation(
    agent=agent,
    persistence_dir="./.conversations",
    workspace=".",
)

try:
    conversation.send_message(
        "Continue the long analysis we started earlier…"
    )
    conversation.run()

except LLMContextWindowExceedError:
    # Conversation is longer than the model’s context window
    # Options:
    # 1) Enable a condenser (recommended for long sessions)
    # 2) Shorten inputs or reset conversation
    print("Hit the context limit. Consider enabling a condenser.")

except LLMAuthenticationError:
    print(
        "Invalid or missing API credentials."
        "Check your API key or auth setup."
    )

except LLMRateLimitError:
    print("Rate limit exceeded. Back off and retry later.")

except LLMTimeoutError:
    print("Request timed out. Consider increasing timeout or retrying.")

except LLMServiceUnavailableError:
    print("Service unavailable or connectivity issue. Retry with backoff.")

except LLMBadRequestError:
    print("Bad request to provider. Validate inputs and arguments.")

except LLMError as e:
    # Fallback for other SDK LLM errors (parsing/validation, etc.)
    print(f"Unhandled LLM error: {e}")

​

Avoiding context‑window errors with a condenser

If a condenser is configured, the SDK emits a condensation request event instead of raising LLMContextWindowExceedError. The agent will summarize older history and continue.

from openhands.sdk.context.condenser import LLMSummarizingCondenser

condenser = LLMSummarizingCondenser(
    llm=llm.model_copy(update={"usage_id": "condenser"}),
    max_size=10,
    keep_first=2,
)

agent = Agent(llm=llm, tools=[], condenser=condenser)
conversation = Conversation(
    agent=agent,
    persistence_dir="./.conversations",
    workspace=".",
)

See the dedicated guide: Context Condenser.

​

Handling errors with direct LLM calls

The same exceptions are raised from both LLM.completion() and LLM.responses() paths, so you can share handlers.

​

Example: Using .completion()

from pydantic import SecretStr
from openhands.sdk import LLM
from openhands.sdk.llm import Message, TextContent
from openhands.sdk.llm.exceptions import (
    LLMError,
    LLMAuthenticationError,
    LLMRateLimitError,
    LLMTimeoutError,
    LLMServiceUnavailableError,
    LLMBadRequestError,
    LLMContextWindowExceedError,
)

llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("your-key"))

try:
    response = llm.completion([
        Message.user([TextContent(text="Summarize our design doc")])
    ])
    print(response.message)

except LLMContextWindowExceedError:
    print("Context window exceeded. Consider enabling a condenser.")
except LLMAuthenticationError:
    print("Invalid or missing API credentials.")
except LLMRateLimitError:
    print("Rate limit exceeded. Back off and retry later.")
except LLMTimeoutError:
    print("Request timed out. Consider increasing timeout or retrying.")
except LLMServiceUnavailableError:
    print("Service unavailable or connectivity issue. Retry with backoff.")
except LLMBadRequestError:
    print("Bad request to provider. Validate inputs and arguments.")
except LLMError as e:
    print(f"Unhandled LLM error: {e}")

​

Example: Using .responses()

from pydantic import SecretStr
from openhands.sdk import LLM
from openhands.sdk.llm import Message, TextContent
from openhands.sdk.llm.exceptions import LLMError, LLMContextWindowExceedError

llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("your-key"))

try:
    resp = llm.responses([
        Message.user(
            [TextContent(text="Write a one-line haiku about code.")]
        )
    ])
    print(resp.message)
except LLMContextWindowExceedError:
    print("Context window exceeded. Consider enabling a condenser.")
except LLMError as e:
    print(f"LLM error: {e}")

​

Rate Limits, Quota, and Budget Denials

LLMRateLimitError can represent a temporary rate limit or an exhausted allowance. Use is_quota_exhaustion_error() to distinguish them instead of parsing the error message in your application:

from openhands.sdk.llm.exceptions import (
    LLMRateLimitError,
    is_quota_exhaustion_error,
)

def report_rate_limit(error: LLMRateLimitError) -> str:
    if is_quota_exhaustion_error(error):
        return "Allowance exhausted. Check the provider's quota or budget."
    return "Temporary rate limit. Retry with backoff."

Temporary rate limits use the configured SDK retry policy. Recognized hard quota errors, such as insufficient_quota and usage_limit_reached, skip retries and can use a configured fallback model. Explicit budget_exceeded denials stop both retries and fallback. A fallback model still uses its own retry policy for temporary failures.

Profile pre-flight validation follows the same distinction: an exhausted quota or budget returns valid: false, while a temporary 429 returns valid: true.

Structured provider code and type fields are recognized even when the human-readable message omits the machine code. This handling is part of the unreleased structured quota fix. Earlier releases can treat these responses as temporary rate limits.

​

Exception reference

All exceptions live under openhands.sdk.llm.exceptions unless noted.

Category	Error	Description
Provider / transport (provider-agnostic)	LLMContextWindowExceedError	Conversation exceeds the model’s context window. Without a condenser, thrown for both Chat and Responses paths.
	LLMAuthenticationError	Invalid or missing credentials (401/403 patterns).
	LLMRateLimitError	Temporary provider rate limit or exhausted quota/budget.
	LLMTimeoutError	SDK or lower-level timeout while waiting for the provider.
	LLMServiceUnavailableError	Temporary connectivity or service outage (e.g., 5xx responses, connection issues).
	LLMBadRequestError	Client-side request issues (invalid parameters, malformed input).
Response parsing / validation	LLMMalformedActionError	Model returned a malformed action.
	LLMNoActionError	Model did not return an action when one was expected.
	LLMResponseError	Could not extract an action from the response.
	FunctionCallConversionError	Failed converting tool/function call payloads.
	FunctionCallValidationError	Tool/function call arguments failed validation.
	FunctionCallNotExistsError	Model referenced an unknown tool or function.
	LLMNoResponseError	Provider returned an empty or invalid response (rare; observed with some Gemini models).
Cancellation	UserCancelledError	A user explicitly aborted the operation.
	OperationCancelled	A running operation was cancelled programmatically.

All of the above (except the explicit cancellation types) inherit from LLMError, so you can implement a catch‑all for unexpected SDK LLM errors while still keeping fine‑grained handlers for the most common cases.