Skip to main content

conductor/
error.rs

1// Copyright {{.Year}} Conductor OSS
2// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
3
4use thiserror::Error;
5
6/// Result type alias for Conductor operations.
7pub type Result<T> = std::result::Result<T, ConductorError>;
8
9/// Main error type for all Conductor SDK operations.
10#[derive(Error, Debug)]
11pub enum ConductorError {
12    /// HTTP request failed.
13    #[error("HTTP error: {0}")]
14    Http(#[from] reqwest::Error),
15
16    /// JSON serialization/deserialization failed.
17    #[error("JSON error: {0}")]
18    Json(#[from] serde_json::Error),
19
20    /// Configuration error.
21    #[error("Configuration error: {0}")]
22    Config(String),
23
24    /// Authentication error.
25    #[error("Authentication error: {0}")]
26    Auth(String),
27
28    /// Task execution error.
29    #[error("Task execution error: {0}")]
30    TaskExecution(String),
31
32    /// Task not found.
33    #[error("Task not found: {0}")]
34    TaskNotFound(String),
35
36    /// Workflow not found.
37    #[error("Workflow not found: {0}")]
38    WorkflowNotFound(String),
39
40    /// Workflow execution error.
41    #[error("Workflow error: {0}")]
42    Workflow(String),
43
44    /// Worker error.
45    #[error("Worker error: {0}")]
46    Worker(String),
47
48    /// Timeout error.
49    #[error("Timeout: {0}")]
50    Timeout(String),
51
52    /// Server error with status code.
53    #[error("Server error ({status}): {message}")]
54    Server { status: u16, message: String },
55
56    /// API error with details.
57    #[error("API error: {message}")]
58    Api {
59        message: String,
60        code: Option<String>,
61    },
62
63    /// Internal error.
64    #[error("Internal error: {0}")]
65    Internal(String),
66
67    /// IO error.
68    #[error("IO error: {0}")]
69    Io(#[from] std::io::Error),
70
71    /// Channel error (for async communication).
72    #[error("Channel error: {0}")]
73    Channel(String),
74
75    /// Agent definition, tool-definition, or agent-config-serialization error.
76    #[cfg(feature = "agents")]
77    #[error("Agent error: {0}")]
78    Agent(String),
79
80    /// One or more declared credentials were not present in `Task.runtime_metadata`.
81    ///
82    /// Credential resolution fails closed: a name a tool/agent declared but that the server
83    /// didn't attach to the polled `Task` is always an error, never a silent fallback to the
84    /// process environment. Carries only the missing *names*, never a value.
85    #[cfg(feature = "agents")]
86    #[error("Required credentials not found: {}", .0.join(", "))]
87    CredentialNotFound(Vec<String>),
88
89    /// A tool/worker failure explicitly marked non-retryable, e.g. a timed-out or
90    /// missing-executable command. A `ToolHandler` returns this instead of any other error
91    /// variant to signal it; the tool-dispatch worker
92    /// (`ToolWorker` in `agents/runtime.rs`) recognizes it and reports
93    /// `WorkerOutput::FailedWithTerminalError` (`FAILED_WITH_TERMINAL_ERROR`) instead of the
94    /// default retryable `Failed`.
95    #[cfg(feature = "agents")]
96    #[error("Terminal tool error: {0}")]
97    TerminalTool(String),
98}
99
100impl ConductorError {
101    /// Create a configuration error.
102    pub fn config(msg: impl Into<String>) -> Self {
103        ConductorError::Config(msg.into())
104    }
105
106    /// Create an authentication error.
107    pub fn auth(msg: impl Into<String>) -> Self {
108        ConductorError::Auth(msg.into())
109    }
110
111    /// Create a task execution error.
112    pub fn task_execution(msg: impl Into<String>) -> Self {
113        ConductorError::TaskExecution(msg.into())
114    }
115
116    /// Create a worker error.
117    pub fn worker(msg: impl Into<String>) -> Self {
118        ConductorError::Worker(msg.into())
119    }
120
121    /// Create an internal error.
122    pub fn internal(msg: impl Into<String>) -> Self {
123        ConductorError::Internal(msg.into())
124    }
125
126    /// Create a server error.
127    pub fn server(status: u16, message: impl Into<String>) -> Self {
128        ConductorError::Server {
129            status,
130            message: message.into(),
131        }
132    }
133
134    /// Create an API error.
135    pub fn api(message: impl Into<String>, code: Option<String>) -> Self {
136        ConductorError::Api {
137            message: message.into(),
138            code,
139        }
140    }
141
142    /// Create an agent error.
143    #[cfg(feature = "agents")]
144    pub fn agent(msg: impl Into<String>) -> Self {
145        ConductorError::Agent(msg.into())
146    }
147
148    /// Create a terminal (non-retryable) tool error — see [`crate::error::ConductorError::TerminalTool`].
149    #[cfg(feature = "agents")]
150    pub fn terminal_tool(msg: impl Into<String>) -> Self {
151        ConductorError::TerminalTool(msg.into())
152    }
153
154    /// Create a "credential not found" error for one or more missing declared credential names.
155    #[cfg(feature = "agents")]
156    pub fn credential_not_found(names: impl IntoIterator<Item = impl Into<String>>) -> Self {
157        ConductorError::CredentialNotFound(names.into_iter().map(Into::into).collect())
158    }
159
160    /// Check if this error is retryable.
161    #[must_use]
162    pub fn is_retryable(&self) -> bool {
163        match self {
164            ConductorError::Http(e) => {
165                e.is_timeout() || e.is_connect() || e.status().is_some_and(|s| s.is_server_error())
166            }
167            ConductorError::Server { status, .. } => *status >= 500,
168            ConductorError::Timeout(_) => true,
169            ConductorError::Channel(_) => false,
170            _ => false,
171        }
172    }
173}