Enum Error 

pub enum Error {
    Http(Error),
    Json(Error),
    Config(String),
    Api(String),
    Stream(String),
    Tool(String),
    InvalidInput(String),
    Timeout,
    Other(String),
}

Comprehensive error type covering all failure modes in the SDK.

This enum uses the thiserror crate to automatically implement std::error::Error and provide well-formatted error messages. Each variant represents a different category of failure that can occur during SDK operation.

Error Categories

• HTTP: Network communication failures (connection errors, timeouts, etc.)
• JSON: Serialization/deserialization failures
• Config: Invalid configuration parameters
• Api: Error responses from the model server
• Stream: Failures during streaming response processing
• Tool: Tool execution or registration failures
• InvalidInput: User-provided input validation failures
• Timeout: Request timeout exceeded
• Other: Catch-all for miscellaneous errors

Automatic Conversions

The #[from] attribute on Http and Json variants enables automatic conversion from reqwest::Error and serde_json::Error using the ? operator, making error propagation seamless.

Variants

Http(Error)

HTTP request failed due to network issues, connection problems, or HTTP errors.

This variant wraps reqwest::Error and is automatically created when using the ? operator on reqwest operations. Common causes include:

• Connection refused (server not running)
• DNS resolution failures
• TLS/SSL certificate errors
• HTTP status errors (4xx, 5xx)
• Network timeouts

Example

let response = client.post(url).send().await?; // Auto-converts reqwest::Error

Json(Error)

JSON serialization or deserialization failed.

This variant wraps serde_json::Error and occurs when:

• Parsing invalid JSON from the API
• Serializing request data fails
• JSON structure doesn’t match expected schema
• Required fields are missing in JSON

Example

let value: MyType = serde_json::from_str(json_str)?; // Auto-converts serde_json::Error

Config(String)

Invalid configuration provided when building AgentOptions.

Occurs during the builder pattern validation phase when required fields are missing or invalid values are provided. Common causes:

• Missing required fields (model, base_url, system_prompt)
• Invalid URL format in base_url
• Invalid timeout values
• Invalid max_tokens or temperature ranges

Example

return Err(Error::config("base_url is required"));

Api(String)

Error response received from the model server’s API.

This indicates the HTTP request succeeded, but the API returned an error response. Common causes:

• Model not found on the server
• Invalid API key or authentication failure
• Rate limiting
• Server-side errors (500, 502, 503)
• Invalid request format

Example

return Err(Error::api("Model 'gpt-4' not found on server"));

Stream(String)

Error occurred while processing the streaming response.

This happens during Server-Sent Events (SSE) parsing or stream processing. Common causes:

• Malformed SSE data
• Connection interrupted mid-stream
• Unexpected end of stream
• Invalid chunk format

Example

return Err(Error::stream("Unexpected end of SSE stream"));

Tool(String)

Tool execution or registration failed.

Occurs when there are problems with tool definitions or execution:

• Tool handler returns an error
• Tool input validation fails
• Tool name collision during registration
• Tool not found when executing
• Invalid tool schema

Example

return Err(Error::tool("Tool 'calculator' not found"));

InvalidInput(String)

Invalid input provided by the user.

Validation error for user-provided data that doesn’t meet requirements:

• Empty prompt string
• Invalid parameter format
• Out of range values
• Malformed input data

Example

return Err(Error::invalid_input("Prompt cannot be empty"));

Timeout

Request exceeded the configured timeout duration.

The operation took longer than the timeout specified in AgentOptions. This is a dedicated variant (no message needed) because the cause is clear.

Example

return Err(Error::timeout());

Other(String)

Miscellaneous error that doesn’t fit other categories.

Catch-all variant for unexpected errors or edge cases that don’t fit into the specific categories above. Should be used sparingly.

Example

return Err(Error::other("Unexpected condition occurred"));

Implementations

impl Error

Implementation of convenience constructors for creating Error instances.

These methods provide a more ergonomic API for creating errors compared to directly constructing the enum variants. They accept impl Into<String>, allowing callers to pass &str, String, or any other type that converts to String.

pub fn config(msg: impl Into<String>) -> Self

Create a new configuration error with a descriptive message.

Use this when validation fails during AgentOptions construction or when invalid configuration values are detected.

Arguments

• msg - Error description explaining what configuration is invalid

Example

use open_agent::Error;

let err = Error::config("base_url must be a valid HTTP or HTTPS URL");
assert_eq!(err.to_string(), "Invalid configuration: base_url must be a valid HTTP or HTTPS URL");

pub fn api(msg: impl Into<String>) -> Self

Create a new API error with the server’s error message.

Use this when the API returns an error response (even if the HTTP request itself succeeded). This typically happens when the server rejects the request due to invalid parameters, missing resources, or server-side failures.

Arguments

• msg - Error message from the API server

Example

use open_agent::Error;

let err = Error::api("Model 'invalid-model' not found");
assert_eq!(err.to_string(), "API error: Model 'invalid-model' not found");

pub fn stream(msg: impl Into<String>) -> Self

Create a new streaming error for SSE parsing or stream processing failures.

Use this when errors occur during Server-Sent Events stream parsing, such as malformed data, unexpected stream termination, or invalid chunks.

Arguments

• msg - Description of the streaming failure

Example

use open_agent::Error;

let err = Error::stream("Unexpected end of SSE stream");
assert_eq!(err.to_string(), "Streaming error: Unexpected end of SSE stream");

pub fn tool(msg: impl Into<String>) -> Self

Create a new tool execution error.

Use this when tool registration, lookup, or execution fails. This includes tool handler errors, missing tools, and invalid tool inputs.

Arguments

• msg - Description of the tool failure

Example

use open_agent::Error;

let err = Error::tool("Calculator tool failed: division by zero");
assert_eq!(err.to_string(), "Tool execution error: Calculator tool failed: division by zero");

pub fn invalid_input(msg: impl Into<String>) -> Self

Create a new invalid input error for user input validation failures.

Use this when user-provided data doesn’t meet requirements, such as empty strings, out-of-range values, or malformed data.

Arguments

• msg - Description of why the input is invalid

Example

use open_agent::Error;

let err = Error::invalid_input("Prompt cannot be empty");
assert_eq!(err.to_string(), "Invalid input: Prompt cannot be empty");

pub fn other(msg: impl Into<String>) -> Self

Create a new miscellaneous error for cases that don’t fit other categories.

Use this sparingly for unexpected conditions that don’t fit into the more specific error variants.

Arguments

• msg - Description of the error

Example

use open_agent::Error;

let err = Error::other("Unexpected internal state");
assert_eq!(err.to_string(), "Error: Unexpected internal state");

pub fn timeout() -> Self

Create a timeout error indicating the operation exceeded the time limit.

Use this when the request or operation takes longer than the configured timeout duration. No message is needed since the cause is self-explanatory.

Example

use open_agent::Error;

let err = Error::timeout();
assert_eq!(err.to_string(), "Request timeout");

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.