diff --git a/CHANGELOG.md b/CHANGELOG.md
index b73c52fc..09caf57d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+* BREAKING: `AgentError` is now an opaque error type which reveals only the general category of error that occurred. `ic-utils` now has its own error types.
+* `AgentError` now contains information about the ongoing operation the error occurred in the context of. This allows you to see if a call successfully went through even if there was for example an error decoding the response.
 * Add `read_state_canister_controllers` and `read_state_canister_module_hash` functions.
 
 ## [0.40.0] - 2025-03-17
diff --git a/Cargo.lock b/Cargo.lock
index 75ac34de..84af06fd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1138,12 +1138,15 @@ dependencies = [
  "ic-certification 3.0.2",
  "ic-transport-types 0.40.0",
  "ic-verify-bls-signature",
+ "ic_principal",
+ "itertools 0.14.0",
  "js-sys",
  "k256",
  "leb128",
  "mockito",
  "p256",
  "pem",
+ "pin-project",
  "pkcs8",
  "rand",
  "rangemap",
@@ -1526,6 +1529,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.12"
@@ -1564,7 +1576,7 @@ dependencies = [
  "ascii-canvas",
  "bit-set",
  "ena",
- "itertools",
+ "itertools 0.11.0",
  "lalrpop-util",
  "petgraph",
  "pico-args",
@@ -1600,9 +1612,9 @@ checksum = "884e2677b40cc8c339eaefcb701c32ef1fd2493d71118dc0ca4b6a736c93bd67"
 
 [[package]]
 name = "libc"
-version = "0.2.164"
+version = "0.2.172"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "433bfe06b8c75da9b2e3fbea6e5329ff87748f0b144ef75306e674c3f6f7c13f"
+checksum = "d750af042f7ef4f724306de029d18836c26c1765a54a6a3f094cbd23a7267ffa"
 
 [[package]]
 name = "libloading"
@@ -1965,6 +1977,26 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315"
 
+[[package]]
+name = "pin-project"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "677f1add503faace112b9f1373e43e9e054bfdd22ff1a63c1bc485eaec6a6a8a"
+dependencies = [
+ "pin-project-internal",
+]
+
+[[package]]
+name = "pin-project-internal"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e918e4ff8c4549eb882f14b3a4bc8c8bc93de829416eacf579f1207a8fbf861"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.87",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.15"
@@ -2208,6 +2240,7 @@ version = "0.0.0"
 dependencies = [
  "candid",
  "ed25519-consensus",
+ "hex",
  "ic-agent",
  "ic-certification 3.0.2",
  "ic-identity-hsm",
@@ -2991,9 +3024,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.41.1"
+version = "1.44.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cfb5bee7a6a52939ca9224d6ac897bb669134078daa8735560897f69de4d33"
+checksum = "e6b88822cbe49de4185e3a4cbf8321dd487cf5fe0c5c65695fef6346371e9c48"
 dependencies = [
  "backtrace",
  "bytes",
@@ -3009,9 +3042,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.4.0"
+version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "693d596312e88961bc67d7f1f97af8a70227d9f90c31bba5806eec004978d752"
+checksum = "6e06d43f1345a3bcd39f6a56dbb7dcab2ba47e68e8ac134855e7e2bdbaf8cab8"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/Cargo.toml b/Cargo.toml
index 419eae8b..daadd7f5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,6 +30,7 @@ ic-utils = { path = "ic-utils", version = "0.40.0" }
 ic-transport-types = { path = "ic-transport-types", version = "0.40.0" }
 
 ic-certification = "3"
+ic_principal = "0.1"
 candid = "0.10.10"
 candid_parser = "0.1.4"
 clap = "4.5.21"
diff --git a/ic-agent/Cargo.toml b/ic-agent/Cargo.toml
index d675432a..78c42a35 100644
--- a/ic-agent/Cargo.toml
+++ b/ic-agent/Cargo.toml
@@ -25,7 +25,6 @@ async-trait = "0.1"
 async-watch = "0.3"
 backoff = "0.4.0"
 cached = { version = "0.52", features = ["ahash"], default-features = false }
-candid = { workspace = true }
 der = "0.7"
 ecdsa = "0.16"
 ed25519-consensus = { workspace = true }
@@ -34,17 +33,20 @@ futures-util = { workspace = true }
 hex = { workspace = true }
 http = "1.0.0"
 http-body = "1.0.0"
+ic_principal = { workspace = true }
 ic-certification = { workspace = true }
 ic-transport-types = { workspace = true }
 ic-verify-bls-signature = "0.5"
+itertools = "0.14.0"
 k256 = { workspace = true, features = ["pem"] }
-p256 = { workspace = true, features = ["pem"] }
 leb128 = { workspace = true }
+p256 = { workspace = true, features = ["pem"] }
+pin-project = "1.1.10"
 pkcs8 = { version = "0.10.2", features = ["std"] }
-sec1 = { version = "0.7.2", features = ["pem"] }
 rand = { workspace = true }
 rangemap = "1.4"
 ring = { version = "0.17", optional = true }
+sec1 = { version = "0.7.2", features = ["pem"] }
 serde = { workspace = true, features = ["derive"] }
 serde_bytes = { workspace = true }
 serde_cbor = { workspace = true }
@@ -78,6 +80,7 @@ wasm-bindgen-futures = { version = "0.4", optional = true }
 web-sys = { version = "0.3", features = ["Window"], optional = true }
 
 [dev-dependencies]
+candid = { workspace = true }
 serde_json.workspace = true
 tracing-subscriber = "0.3"
 tracing = "0.1"
diff --git a/ic-agent/src/agent/agent_error.rs b/ic-agent/src/agent/agent_error.rs
index 006b0f23..0c8a00e9 100644
--- a/ic-agent/src/agent/agent_error.rs
+++ b/ic-agent/src/agent/agent_error.rs
@@ -1,63 +1,153 @@
-//! Errors that can occur when using the replica agent.
+//! Errors that can occur when using the agent.
 
-use crate::{agent::status::Status, RequestIdError};
-use candid::Principal;
 use ic_certification::Label;
-use ic_transport_types::{InvalidRejectCodeError, RejectResponse};
-use leb128::read;
-use std::time::Duration;
+use ic_transport_types::RejectResponse;
 use std::{
+    error::Error,
     fmt::{Debug, Display, Formatter},
-    str::Utf8Error,
+    time::Duration,
 };
 use thiserror::Error;
 
-/// An error that occurred when using the agent.
-#[derive(Error, Debug)]
-pub enum AgentError {
-    /// The replica URL was invalid.
-    #[error(r#"Invalid Replica URL: "{0}""#)]
-    InvalidReplicaUrl(String),
+use crate::util::try_from_context;
 
-    /// The request timed out.
-    #[error("The request timed out.")]
-    TimeoutWaitingForResponse(),
+use super::{status::Status, OperationInfo, CURRENT_OPERATION};
 
-    /// An error occurred when signing with the identity.
-    #[error("Identity had a signing error: {0}")]
-    SigningError(String),
+/// An error that can occur when using an `Agent`. Includes partial operation info.
+///
+/// If (say) a deserialization hiccup occurred after a call returned, you can call the
+/// [`operation_info()`](Self::operation_info) method to learn whether the call failed or succeeded,
+/// and (if possible) what the response was.
+pub struct AgentError {
+    inner: Box<AgentErrorInner>,
+}
+
+#[derive(Debug)]
+struct AgentErrorInner {
+    source: Option<Box<dyn Error + Send + Sync>>,
+    kind: ErrorKind,
+    operation_info: Option<OperationInfo>,
+}
 
-    /// The data fetched was invalid CBOR.
-    #[error("Invalid CBOR data, could not deserialize: {0}")]
-    InvalidCborData(#[from] serde_cbor::Error),
+/// What category of error occurred.
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+pub enum ErrorKind {
+    /// Errors relating to certificate and signature verification. Plausibly due to malicious nodes,
+    /// but far more likely due to running mainnet-targeting code against a dev instance.
+    Trust,
+    /// Errors relating to the IC protocol as defined by the specification (e.g. CBOR decoding).
+    Protocol,
+    /// Reject messages provided by the IC. Note that unless the [`OperationStatus`](super::OperationStatus)
+    /// is `Received`, a reject cannot necessarily be trusted.
+    Reject,
+    /// Errors relating to the HTTP transport (e.g. TCP errors).
+    Transport,
+    /// Errors from a pluggable interface (e.g. [`Identity`](super::Identity)).
+    External,
+    /// Errors caused by hitting a user-provided limit (e.g. response body size).
+    Limit,
+    /// Errors caused by invalid input to a function.
+    Input,
+    /// Uncategorizable errors.
+    Unknown,
+}
 
-    /// There was an error calculating a request ID.
-    #[error("Cannot calculate a RequestID: {0}")]
-    CannotCalculateRequestId(#[from] RequestIdError),
+impl AgentError {
+    /// Returns what kind of error occurred.
+    pub fn kind(&self) -> ErrorKind {
+        self.inner.kind
+    }
+    /// Returns details on whatever operation was ongoing, or `None` if there wasn't one.
+    pub fn operation_info(&self) -> Option<&OperationInfo> {
+        self.inner.operation_info.as_ref()
+    }
+    /// Creates a new error for use in the [`RouteProvider`](super::RouteProvider) interface.
+    /// `operation_info` will return `None` initially, this will be inserted by the agent.
+    pub fn new_route_provider_error_without_context(message: String) -> Self {
+        Self {
+            inner: Box::new(AgentErrorInner {
+                source: Some(Box::new(ErrorCode::RouteProviderError(message))),
+                kind: ErrorKind::External,
+                operation_info: None,
+            }),
+        }
+    }
+    pub(crate) fn from_boxed_in_context(
+        inner: Box<dyn Error + Send + Sync>,
+        kind: ErrorKind,
+    ) -> Self {
+        match inner.downcast::<AgentError>() {
+            Ok(agent_err) => *agent_err,
+            Err(source) => AgentError {
+                inner: Box::new(AgentErrorInner {
+                    kind,
+                    operation_info: try_from_context(&CURRENT_OPERATION, |op| op.clone()).ok(),
+                    source: Some(source),
+                }),
+            },
+        }
+    }
+    pub(crate) fn add_context(&mut self) {
+        self.inner.operation_info = try_from_context(&CURRENT_OPERATION, |op| op.clone()).ok();
+    }
+    /// If this error is an HTTP error, retrieve the the payload. Equivalent to downcasting [`source()`](Error::source).
+    pub fn as_http_error(&self) -> Option<&HttpErrorPayload> {
+        self.inner
+            .source
+            .as_ref()
+            .and_then(|source| source.downcast_ref())
+    }
 
-    /// There was an error when de/serializing with Candid.
-    #[error("Candid returned an error: {0}")]
-    CandidError(Box<dyn Send + Sync + std::error::Error>),
+    /// If this error is/contains a reject (whether certified or not), returns it.
+    pub fn as_reject(&self) -> Option<&RejectResponse> {
+        if let Some(Err(reject)) = self
+            .inner
+            .operation_info
+            .as_ref()
+            .and_then(|op| op.response())
+        {
+            Some(reject)
+        } else if let Some(
+            ErrorCode::CertifiedReject { reject } | ErrorCode::UncertifiedReject { reject },
+        ) = self
+            .inner
+            .source
+            .as_ref()
+            .and_then(|source| source.downcast_ref::<ErrorCode>())
+        {
+            Some(reject)
+        } else {
+            None
+        }
+    }
+}
 
-    /// There was an error parsing a URL.
-    #[error(r#"Cannot parse url: "{0}""#)]
-    UrlParseError(#[from] url::ParseError),
+impl Debug for AgentError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AgentError")
+            .field("source", &self.inner.source)
+            .field("kind", &self.inner.kind)
+            .field("operation_info", &self.inner.operation_info)
+            .finish()
+    }
+}
 
-    /// The HTTP method was invalid.
-    #[error(r#"Invalid method: "{0}""#)]
-    InvalidMethodError(#[from] http::method::InvalidMethod),
+/// An error that occurred when using the agent.
+#[derive(Error, Debug)]
+pub(crate) enum ErrorCode {
+    /// The request timed out.
+    #[error("The request timed out.")]
+    TimeoutWaitingForResponse,
 
-    /// The principal string was not a valid principal.
-    #[error("Cannot parse Principal: {0}")]
-    PrincipalError(#[from] crate::export::PrincipalError),
+    /// An error occurred when signing with the identity.
+    #[error("Identity had a signing error: {0}")]
+    SigningError(String),
 
     /// The subnet rejected the message.
     #[error("The replica returned a rejection error: reject code {:?}, reject message {}, error code {:?}", .reject.reject_code, .reject.reject_message, .reject.error_code)]
     CertifiedReject {
         /// The rejection returned by the replica.
         reject: RejectResponse,
-        /// The operation that was rejected. Not always available.
-        operation: Option<Operation>,
     },
 
     /// The subnet may have rejected the message. This rejection cannot be verified as authentic.
@@ -65,14 +155,8 @@ pub enum AgentError {
     UncertifiedReject {
         /// The rejection returned by the boundary node.
         reject: RejectResponse,
-        /// The operation that was rejected. Not always available.
-        operation: Option<Operation>,
     },
 
-    /// The replica returned an HTTP error.
-    #[error("The replica returned an HTTP Error: {0}")]
-    HttpError(HttpErrorPayload),
-
     /// The status endpoint returned an invalid status.
     #[error("Status endpoint returned an invalid status.")]
     InvalidReplicaStatus,
@@ -81,37 +165,13 @@ pub enum AgentError {
     #[error("Call was marked as done but we never saw the reply. Request ID: {0}")]
     RequestStatusDoneNoReply(String),
 
-    /// A string error occurred in an external tool.
-    #[error("A tool returned a string message error: {0}")]
-    MessageError(String),
-
-    /// There was an error reading a LEB128 value.
-    #[error("Error reading LEB128 value: {0}")]
-    Leb128ReadError(#[from] read::Error),
-
-    /// A string was invalid UTF-8.
-    #[error("Error in UTF-8 string: {0}")]
-    Utf8ReadError(#[from] Utf8Error),
-
-    /// The lookup path was absent in the certificate.
-    #[error("The lookup path ({0:?}) is absent in the certificate.")]
-    LookupPathAbsent(Vec<Label>),
-
-    /// The lookup path was unknown in the certificate.
-    #[error("The lookup path ({0:?}) is unknown in the certificate.")]
-    LookupPathUnknown(Vec<Label>),
-
     /// The lookup path did not make sense for the certificate.
     #[error("The lookup path ({0:?}) does not make sense for the certificate.")]
     LookupPathError(Vec<Label>),
 
-    /// The request status at the requested path was invalid.
-    #[error("The request status ({1}) at path {0:?} is invalid.")]
-    InvalidRequestStatus(Vec<Label>, String),
-
     /// The certificate verification for a `read_state` call failed.
     #[error("Certificate verification failed.")]
-    CertificateVerificationFailed(),
+    CertificateVerificationFailed,
 
     /// The signature verification for a query call failed.
     #[error("Query signature verification failed.")]
@@ -119,10 +179,10 @@ pub enum AgentError {
 
     /// The certificate contained a delegation that does not include the `effective_canister_id` in the `canister_ranges` field.
     #[error("Certificate is not authorized to respond to queries for this canister. While developing: Did you forget to set effective_canister_id?")]
-    CertificateNotAuthorized(),
+    CertificateNotAuthorized,
 
     /// The certificate was older than allowed by the `ingress_expiry`.
-    #[error("Certificate is stale (over {0:?}). Is the computer's clock synchronized?")]
+    #[error("Certificate is stale (over {}s). Is the computer's clock synchronized?", .0.as_secs())]
     CertificateOutdated(Duration),
 
     /// The certificate contained more than one delegation.
@@ -174,40 +234,9 @@ pub enum AgentError {
     #[error("The status response did not contain a root key.  Status: {0}")]
     NoRootKeyInStatus(Status),
 
-    /// The invocation to the wallet call forward method failed with an error.
-    #[error("The invocation to the wallet call forward method failed with the error: {0}")]
-    WalletCallFailed(String),
-
-    /// The wallet operation failed.
-    #[error("The  wallet operation failed: {0}")]
-    WalletError(String),
-
-    /// The wallet canister must be upgraded. See [`dfx wallet upgrade`](https://internetcomputer.org/docs/current/references/cli-reference/dfx-wallet)
-    #[error("The wallet canister must be upgraded: {0}")]
-    WalletUpgradeRequired(String),
-
     /// The response size exceeded the provided limit.
     #[error("Response size exceeded limit.")]
-    ResponseSizeExceededLimit(),
-
-    /// An unknown error occurred during communication with the replica.
-    #[error("An error happened during communication with the replica: {0}")]
-    TransportError(#[from] reqwest::Error),
-
-    /// There was a mismatch between the expected and actual CBOR data during inspection.
-    #[error("There is a mismatch between the CBOR encoded call and the arguments: field {field}, value in argument is {value_arg}, value in CBOR is {value_cbor}")]
-    CallDataMismatch {
-        /// The field that was mismatched.
-        field: String,
-        /// The value that was expected to be in the CBOR.
-        value_arg: String,
-        /// The value that was actually in the CBOR.
-        value_cbor: String,
-    },
-
-    /// The rejected call had an invalid reject code (valid range 1..5).
-    #[error(transparent)]
-    InvalidRejectCode(#[from] InvalidRejectCodeError),
+    ResponseSizeExceededLimit,
 
     /// Route provider failed to generate a url for some reason.
     #[error("Route provider failed to generate url: {0}")]
@@ -216,6 +245,42 @@ pub enum AgentError {
     /// Invalid HTTP response.
     #[error("Invalid HTTP response: {0}")]
     InvalidHttpResponse(String),
+
+    /// Wrong envelope type for function.
+    #[error("Wrong request type {found}, expected {expected}")]
+    WrongRequestType { found: String, expected: String },
+}
+
+impl Error for AgentError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        self.inner.source.as_ref().map(|s| &**s as _)
+    }
+}
+
+impl Display for AgentError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self.inner.kind {
+            ErrorKind::External => {
+                if let Some(source) = &self.inner.source {
+                    write!(f, "{source}")?;
+                } else {
+                    write!(f, "unknown internal module error")?;
+                }
+                return Ok(());
+            }
+            ErrorKind::Input => write!(f, "input precondition failed")?,
+            ErrorKind::Limit => write!(f, "internal limit reached")?,
+            ErrorKind::Protocol => write!(f, "IC protocol error")?,
+            ErrorKind::Reject => write!(f, "call rejected")?,
+            ErrorKind::Transport => write!(f, "HTTP transport error")?,
+            ErrorKind::Trust => write!(f, "trust error")?,
+            ErrorKind::Unknown => write!(f, "internal error")?,
+        }
+        if let Some(source) = &self.inner.source {
+            write!(f, ": {source}")?;
+        }
+        Ok(())
+    }
 }
 
 impl PartialEq for AgentError {
@@ -226,9 +291,13 @@ impl PartialEq for AgentError {
     }
 }
 
-impl From<candid::Error> for AgentError {
-    fn from(e: candid::Error) -> AgentError {
-        AgentError::CandidError(e.into())
+pub(crate) trait ResultExt<T> {
+    fn context(self, kind: ErrorKind) -> Result<T, AgentError>;
+}
+
+impl<T, E: Error + Send + Sync + 'static> ResultExt<T> for Result<T, E> {
+    fn context(self, kind: ErrorKind) -> Result<T, AgentError> {
+        self.map_err(|e| AgentError::from_boxed_in_context(Box::new(e), kind))
     }
 }
 
@@ -244,19 +313,21 @@ pub struct HttpErrorPayload {
 
 impl HttpErrorPayload {
     fn fmt_human_readable(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
-        // No matter content_type is TEXT or not,
-        // always try to parse it as a String.
-        // When fail, print the raw byte array
-        f.write_fmt(format_args!(
-            "Http Error: status {}, content type {:?}, content: {}",
-            http::StatusCode::from_u16(self.status)
-                .map_or_else(|_| format!("{}", self.status), |code| format!("{code}")),
-            self.content_type.clone().unwrap_or_default(),
-            String::from_utf8(self.content.clone()).unwrap_or_else(|_| format!(
-                "(unable to decode content as UTF-8: {:?})",
-                self.content
-            ))
-        ))?;
+        // No matter whether content_type is text/* or not, always try to parse it as a string.
+        // If this fails, print hex.
+        let status = http::StatusCode::from_u16(self.status)
+            .map_or_else(|_| format!("{}", self.status), |code| format!("{code}"));
+        let content_type = self.content_type.as_deref().unwrap_or("<none>");
+        if let Ok(content) = std::str::from_utf8(&self.content) {
+            f.write_fmt(format_args!(
+                r#"replica HTTP error: {content:?} (HTTP code {status}, content type {content_type:?})"#
+            ))?;
+        } else {
+            f.write_fmt(format_args!(
+                r#"replica HTTP error: 0x{} (non-UTF-8) (HTTP code {status}, content type {content_type:?})"#,
+                hex::encode(&self.content)
+            ))?;
+        }
         Ok(())
     }
 }
@@ -273,36 +344,52 @@ impl Display for HttpErrorPayload {
     }
 }
 
-/// An operation that can result in a reject.
-#[derive(Debug, Clone, Eq, PartialEq)]
-pub enum Operation {
-    /// A call to a canister method.
-    Call {
-        /// The canister whose method was called.
-        canister: Principal,
-        /// The name of the method.
-        method: String,
-    },
-    /// A read of the state tree, in the context of a canister. This will *not* be returned for request polling.
-    ReadState {
-        /// The requested paths within the state tree.
-        paths: Vec<Vec<String>>,
-        /// The canister the read request was made in the context of.
-        canister: Principal,
-    },
-    /// A read of the state tree, in the context of a subnet.
-    ReadSubnetState {
-        /// The requested paths within the state tree.
-        paths: Vec<Vec<String>>,
-        /// The subnet the read request was made in the context of.
-        subnet: Principal,
+impl Error for HttpErrorPayload {}
+
+impl AsRef<AgentError> for AgentError {
+    fn as_ref(&self) -> &AgentError {
+        self
+    }
+}
+
+/// Errors produced by the `inspect_*` family of [`Agent`] methods.
+#[derive(Debug)]
+pub enum InspectionError {
+    /// A field did not match.
+    CallDataMismatch {
+        /// The field that was mismatched.
+        field: String,
+        /// The value that was expected to be in the CBOR.
+        value_arg: String,
+        /// The value that was actually in the CBOR.
+        value_cbor: String,
     },
+    /// Failed for another reason (e.g. decoding).
+    Other(AgentError),
+}
+
+impl Display for InspectionError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            InspectionError::CallDataMismatch { field, value_arg, value_cbor } => write!(f, "mismatch between the CBOR encoded call and the arguments: field {field}, value in argument is {value_arg}, value in CBOR is {value_cbor}"),
+            InspectionError::Other(error) => write!(f, "inspection error: {error}"),
+        }
+    }
+}
+
+impl Error for InspectionError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        if let Self::Other(err) = self {
+            Some(err)
+        } else {
+            None
+        }
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::HttpErrorPayload;
-    use crate::AgentError;
 
     #[test]
     fn content_type_none_valid_utf8() {
@@ -313,8 +400,8 @@ mod tests {
         };
 
         assert_eq!(
-            format!("{}", AgentError::HttpError(payload)),
-            r#"The replica returned an HTTP Error: Http Error: status 420 <unknown status code>, content type "", content: hello"#,
+            format!("{payload}"),
+            r#"replica HTTP error: "hello" (HTTP code 420 <unknown status code>, content type "<none>")"#,
         );
     }
 
@@ -325,10 +412,9 @@ mod tests {
             content_type: None,
             content: vec![195, 40],
         };
-
         assert_eq!(
-            format!("{}", AgentError::HttpError(payload)),
-            r#"The replica returned an HTTP Error: Http Error: status 420 <unknown status code>, content type "", content: (unable to decode content as UTF-8: [195, 40])"#,
+            format!("{payload}"),
+            r#"replica HTTP error: 0xc328 (non-UTF-8) (HTTP code 420 <unknown status code>, content type "<none>")"#,
         );
     }
 
@@ -341,8 +427,8 @@ mod tests {
         };
 
         assert_eq!(
-            format!("{}", AgentError::HttpError(payload)),
-            r#"The replica returned an HTTP Error: Http Error: status 420 <unknown status code>, content type "text/plain", content: hello"#,
+            format!("{payload}"),
+            r#"replica HTTP error: "hello" (HTTP code 420 <unknown status code>, content type "text/plain")"#,
         );
     }
 
@@ -355,8 +441,8 @@ mod tests {
         };
 
         assert_eq!(
-            format!("{}", AgentError::HttpError(payload)),
-            r#"The replica returned an HTTP Error: Http Error: status 420 <unknown status code>, content type "text/plain; charset=utf-8", content: hello"#,
+            format!("{payload}"),
+            r#"replica HTTP error: "hello" (HTTP code 420 <unknown status code>, content type "text/plain; charset=utf-8")"#,
         );
     }
 
@@ -369,8 +455,8 @@ mod tests {
         };
 
         assert_eq!(
-            format!("{}", AgentError::HttpError(payload)),
-            r#"The replica returned an HTTP Error: Http Error: status 420 <unknown status code>, content type "text/html", content: world"#,
+            format!("{payload}"),
+            r#"replica HTTP error: "world" (HTTP code 420 <unknown status code>, content type "text/html")"#,
         );
     }
 }
diff --git a/ic-agent/src/agent/agent_test.rs b/ic-agent/src/agent/agent_test.rs
index bcbc7bb8..810da66e 100644
--- a/ic-agent/src/agent/agent_test.rs
+++ b/ic-agent/src/agent/agent_test.rs
@@ -1,14 +1,16 @@
 use self::mock::{
     assert_mock, assert_single_mock, assert_single_mock_count, mock, mock_additional,
 };
-use crate::{agent::Status, export::Principal, Agent, AgentError, Certificate};
+use crate::{
+    agent::Status, agent_error::ErrorKind, export::Principal, Agent, AgentError, Certificate,
+};
 use candid::{Encode, Nat};
 use futures_util::FutureExt;
 use ic_certification::{Delegation, Label};
 use ic_transport_types::{
     NodeSignature, QueryResponse, RejectCode, RejectResponse, ReplyResponse, TransportCallResponse,
 };
-use std::{collections::BTreeMap, str::FromStr, sync::Arc, time::Duration};
+use std::{collections::BTreeMap, error::Error, str::FromStr, sync::Arc, time::Duration};
 #[cfg(all(target_family = "wasm", feature = "wasm-bindgen"))]
 use wasm_bindgen_test::wasm_bindgen_test;
 
@@ -52,7 +54,7 @@ fn make_certifying_agent(url: &str) -> Agent {
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
-async fn query() -> Result<(), AgentError> {
+async fn query() -> Result<(), Box<dyn Error + Send + Sync>> {
     let blob = Vec::from("Hello World");
     let response = QueryResponse::Replied {
         reply: ReplyResponse { arg: blob.clone() },
@@ -116,7 +118,7 @@ async fn query_error() -> Result<(), AgentError> {
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
-async fn query_rejected() -> Result<(), AgentError> {
+async fn query_rejected() -> Result<(), Box<dyn Error + Send + Sync>> {
     let response: QueryResponse = QueryResponse::Rejected {
         reject: RejectResponse {
             reject_code: RejectCode::DestinationInvalid,
@@ -152,10 +154,15 @@ async fn query_rejected() -> Result<(), AgentError> {
     assert_mock(query_mock).await;
 
     match result {
-        Err(AgentError::UncertifiedReject {
-            reject: replica_error,
-            ..
-        }) => {
+        Err(err) if err.kind() == ErrorKind::Reject => {
+            let replica_error = err
+                .operation_info()
+                .unwrap()
+                .response
+                .as_ref()
+                .unwrap()
+                .as_ref()
+                .unwrap_err();
             assert_eq!(replica_error.reject_code, RejectCode::DestinationInvalid);
             assert_eq!(replica_error.reject_message, "Rejected Message");
             assert_eq!(replica_error.error_code, Some("Error code".to_string()));
@@ -217,11 +224,16 @@ async fn call_rejected() -> Result<(), AgentError> {
         .await;
 
     assert_mock(call_mock).await;
-
-    assert!(
-        matches!(result, Err(AgentError::UncertifiedReject { reject, .. }) if reject == reject_response)
-    );
-
+    let agent_error = result.unwrap_err();
+    assert_eq!(agent_error.kind(), ErrorKind::Reject);
+    let operation_info = agent_error.operation_info().unwrap();
+    let reject = operation_info
+        .response
+        .as_ref()
+        .unwrap()
+        .as_ref()
+        .unwrap_err();
+    assert_eq!(*reject, reject_response);
     Ok(())
 }
 
@@ -258,17 +270,23 @@ async fn call_rejected_without_error_code() -> Result<(), AgentError> {
         .await;
 
     assert_mock(call_mock).await;
-
-    assert!(
-        matches!(result, Err(AgentError::UncertifiedReject { reject, .. }) if reject == non_replicated_reject)
-    );
+    let agent_error = result.unwrap_err();
+    assert_eq!(agent_error.kind(), ErrorKind::Reject);
+    let operation_info = agent_error.operation_info().unwrap();
+    let reject = operation_info
+        .response
+        .as_ref()
+        .unwrap()
+        .as_ref()
+        .unwrap_err();
+    assert_eq!(*reject, non_replicated_reject);
 
     Ok(())
 }
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
-async fn status() -> Result<(), AgentError> {
+async fn status() -> Result<(), Box<dyn Error + Send + Sync>> {
     let map = BTreeMap::new();
     let response = serde_cbor::Value::Map(map);
     let (read_mock, url) = mock(
@@ -291,7 +309,7 @@ async fn status() -> Result<(), AgentError> {
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
 #[cfg_attr(target_family = "wasm", wasm_bindgen_test)]
-async fn status_okay() -> Result<(), AgentError> {
+async fn status_okay() -> Result<(), Box<dyn Error + Send + Sync>> {
     let map = BTreeMap::new();
     let response = serde_cbor::Value::Map(map);
     let (read_mock, url) = mock(
@@ -314,7 +332,8 @@ async fn status_okay() -> Result<(), AgentError> {
 }
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
-async fn reqwest_client_status_okay_when_request_retried() -> Result<(), AgentError> {
+async fn reqwest_client_status_okay_when_request_retried(
+) -> Result<(), Box<dyn Error + Send + Sync>> {
     let map = BTreeMap::new();
     let response = serde_cbor::Value::Map(map);
     let (read_mock, url) = mock(
@@ -431,7 +450,7 @@ async fn check_subnet_range_with_unauthorized_range() {
             wrong_canister,
         )
         .await;
-    assert_eq!(result, Err(AgentError::CertificateNotAuthorized()));
+    assert_eq!(result.unwrap_err().kind(), ErrorKind::Trust);
 }
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
@@ -496,10 +515,7 @@ async fn wrong_subnet_query_certificate() {
     .await;
     let agent = make_certifying_agent(&url);
     let result = agent.query(&canister, "getVersion").call().await;
-    assert!(matches!(
-        result.unwrap_err(),
-        AgentError::CertificateNotAuthorized()
-    ));
+    assert_eq!(result.unwrap_err().kind(), ErrorKind::Trust);
     assert_single_mock(
         "POST",
         "/api/v2/canister/224od-giaaa-aaaao-ae5vq-cai/read_state",
@@ -538,7 +554,7 @@ async fn no_cert() {
     .await;
     let agent = make_certifying_agent(&url);
     let result = agent.query(&canister, "getVersion").call().await;
-    assert!(matches!(result.unwrap_err(), AgentError::MissingSignature));
+    assert_eq!(result.unwrap_err().kind(), ErrorKind::Trust);
     assert_mock(read_mock).await;
 }
 
@@ -586,10 +602,10 @@ async fn too_many_delegations() {
         .await
         .expect("read state failed");
     let new_cert = self_delegate_cert(&subnet_id, &cert, 1);
-    assert!(matches!(
-        agent.verify(&new_cert, canister_id).unwrap_err(),
-        AgentError::CertificateHasTooManyDelegations
-    ));
+    assert_eq!(
+        agent.verify(&new_cert, canister_id).unwrap_err().kind(),
+        ErrorKind::Protocol
+    );
 }
 
 #[cfg_attr(not(target_family = "wasm"), tokio::test)]
diff --git a/ic-agent/src/agent/mod.rs b/ic-agent/src/agent/mod.rs
index 1263b8ca..fd0a96e4 100644
--- a/ic-agent/src/agent/mod.rs
+++ b/ic-agent/src/agent/mod.rs
@@ -13,7 +13,7 @@ pub mod status;
 
 pub use agent_config::AgentConfig;
 pub use agent_error::AgentError;
-use agent_error::{HttpErrorPayload, Operation};
+use agent_error::{ErrorCode, ErrorKind::*, HttpErrorPayload, InspectionError, ResultExt};
 use async_lock::Semaphore;
 use async_trait::async_trait;
 pub use builder::AgentBuilder;
@@ -29,6 +29,7 @@ pub use ic_transport_types::{
 pub use nonce::{NonceFactory, NonceGenerator};
 use rangemap::{RangeInclusiveMap, RangeInclusiveSet, StepFns};
 use reqwest::{Body, Client, Request, Response};
+use response_authentication::LookupError;
 use route_provider::{
     dynamic_routing::{
         dynamic_route_provider::DynamicRouteProviderBuilder, node::Node,
@@ -38,6 +39,7 @@ use route_provider::{
 };
 use time::OffsetDateTime;
 use tower_service::Service;
+use url::Url;
 
 #[cfg(test)]
 mod agent_test;
@@ -49,7 +51,8 @@ use crate::{
     },
     export::Principal,
     identity::Identity,
-    to_request_id, RequestId,
+    util::{in_context_of, try_from_context},
+    RequestId,
 };
 use backoff::{backoff::Backoff, ExponentialBackoffBuilder};
 use backoff::{exponential::ExponentialBackoff, SystemClock};
@@ -58,12 +61,12 @@ use ic_transport_types::{
     signed::{SignedQuery, SignedRequestStatus, SignedUpdate},
     QueryResponse, ReadStateResponse, SubnetMetrics, TransportCallResponse,
 };
-use serde::Serialize;
 use status::Status;
 use std::{
     borrow::Cow,
     collections::HashMap,
     convert::TryFrom,
+    error::Error,
     fmt::{self, Debug},
     future::{Future, IntoFuture},
     pin::Pin,
@@ -275,7 +278,7 @@ impl Agent {
         }
         let status = self.status().await?;
         let Some(root_key) = status.root_key else {
-            return Err(AgentError::NoRootKeyInStatus(status));
+            return Err(ErrorCode::NoRootKeyInStatus(status)).context(Protocol);
         };
         self.set_root_key(root_key);
         Ok(())
@@ -308,14 +311,12 @@ impl Agent {
         self.identity.sender()
     }
 
-    async fn query_endpoint<A>(
+    /// This function should only be entered from `query_inner`.
+    async fn query_endpoint(
         &self,
         effective_canister_id: Principal,
         serialized_bytes: Vec<u8>,
-    ) -> Result<A, AgentError>
-    where
-        A: serde::de::DeserializeOwned,
-    {
+    ) -> Result<QueryResponse, AgentError> {
         let _permit = self.concurrent_requests_semaphore.acquire().await;
         let bytes = self
             .execute(
@@ -325,17 +326,23 @@ impl Agent {
             )
             .await?
             .1;
-        serde_cbor::from_slice(&bytes).map_err(AgentError::InvalidCborData)
+        let resp = serde_cbor::from_slice(&bytes).context(Protocol)?;
+        try_from_context(&CURRENT_OPERATION, |op| {
+            op.response = Some(match &resp {
+                QueryResponse::Replied { reply, .. } => Ok(reply.arg.clone()),
+                QueryResponse::Rejected { reject, .. } => Err(reject.clone()),
+            })
+        })
+        .ok();
+        Ok(resp)
     }
 
-    async fn read_state_endpoint<A>(
+    /// Make sure to set `CURRENT_OPERATION` before calling this.
+    async fn read_state_endpoint(
         &self,
         effective_canister_id: Principal,
         serialized_bytes: Vec<u8>,
-    ) -> Result<A, AgentError>
-    where
-        A: serde::de::DeserializeOwned,
-    {
+    ) -> Result<ReadStateResponse, AgentError> {
         let _permit = self.concurrent_requests_semaphore.acquire().await;
         let endpoint = format!(
             "api/v2/canister/{}/read_state",
@@ -345,9 +352,10 @@ impl Agent {
             .execute(Method::POST, &endpoint, Some(serialized_bytes))
             .await?
             .1;
-        serde_cbor::from_slice(&bytes).map_err(AgentError::InvalidCborData)
+        serde_cbor::from_slice(&bytes).context(Protocol)
     }
 
+    /// Make sure to set `CURRENT_OPERATION` before calling this.
     async fn read_subnet_state_endpoint<A>(
         &self,
         subnet_id: Principal,
@@ -362,9 +370,10 @@ impl Agent {
             .execute(Method::POST, &endpoint, Some(serialized_bytes))
             .await?
             .1;
-        serde_cbor::from_slice(&bytes).map_err(AgentError::InvalidCborData)
+        serde_cbor::from_slice(&bytes).context(Protocol)
     }
 
+    /// Make sure to set `CURRENT_OPERATION` before calling this.
     async fn call_endpoint(
         &self,
         effective_canister_id: Principal,
@@ -380,11 +389,10 @@ impl Agent {
             return Ok(TransportCallResponse::Accepted);
         }
 
-        serde_cbor::from_slice(&response_body).map_err(AgentError::InvalidCborData)
+        serde_cbor::from_slice(&response_body).context(Protocol)
     }
 
-    /// The simplest way to do a query call; sends a byte array and will return a byte vector.
-    /// The encoding is left as an exercise to the user.
+    /// All query functions except `query_signed` should route through this method.
     #[allow(clippy::too_many_arguments)]
     async fn query_raw(
         &self,
@@ -396,24 +404,30 @@ impl Agent {
         use_nonce: bool,
         explicit_verify_query_signatures: Option<bool>,
     ) -> Result<Vec<u8>, AgentError> {
-        let operation = Operation::Call {
-            canister: canister_id,
-            method: method_name.clone(),
-        };
-        let content = self.query_content(
-            canister_id,
-            method_name,
-            arg,
-            ingress_expiry_datetime,
-            use_nonce,
-        )?;
-        let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
-        self.query_inner(
-            effective_canister_id,
-            serialized_bytes,
-            content.to_request_id(),
-            explicit_verify_query_signatures,
-            operation,
+        let expiry = ingress_expiry_datetime.unwrap_or_else(|| self.get_expiry_date());
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                status: OperationStatus::NotSent,
+                operation: Operation::Query {
+                    canister: canister_id,
+                    method: method_name.clone(),
+                },
+                expiry,
+                response: None,
+            },
+            async {
+                let content =
+                    self.query_content(canister_id, method_name, arg, expiry, use_nonce)?;
+                let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
+                self.query_inner(
+                    effective_canister_id,
+                    serialized_bytes,
+                    content.to_request_id(),
+                    explicit_verify_query_signatures,
+                )
+                .await
+            },
         )
         .await
     }
@@ -426,35 +440,45 @@ impl Agent {
         effective_canister_id: Principal,
         signed_query: Vec<u8>,
     ) -> Result<Vec<u8>, AgentError> {
-        let envelope: Envelope =
-            serde_cbor::from_slice(&signed_query).map_err(AgentError::InvalidCborData)?;
+        let envelope: Envelope = serde_cbor::from_slice(&signed_query).context(Input)?;
         let EnvelopeContent::Query {
             canister_id,
             method_name,
+            ingress_expiry,
             ..
         } = &*envelope.content
         else {
-            return Err(AgentError::CallDataMismatch {
-                field: "request_type".to_string(),
-                value_arg: "query".to_string(),
-                value_cbor: if matches!(*envelope.content, EnvelopeContent::Call { .. }) {
+            return Err(ErrorCode::WrongRequestType {
+                expected: "query".to_string(),
+                found: if matches!(*envelope.content, EnvelopeContent::Call { .. }) {
                     "update"
                 } else {
                     "read_state"
                 }
                 .to_string(),
-            });
-        };
-        let operation = Operation::Call {
-            canister: *canister_id,
-            method: method_name.clone(),
+            })
+            .context(Input);
         };
-        self.query_inner(
-            effective_canister_id,
-            signed_query,
-            envelope.content.to_request_id(),
-            None,
-            operation,
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                status: OperationStatus::NotSent,
+                operation: Operation::Query {
+                    canister: *canister_id,
+                    method: method_name.clone(),
+                },
+                expiry: *ingress_expiry,
+                response: None,
+            },
+            async {
+                self.query_inner(
+                    effective_canister_id,
+                    signed_query,
+                    envelope.content.to_request_id(),
+                    None,
+                )
+                .await
+            },
         )
         .await
     }
@@ -462,33 +486,35 @@ impl Agent {
     /// Helper function for performing both the query call and possibly a `read_state` to check the subnet node keys.
     ///
     /// This should be used instead of `query_endpoint`. No validation is performed on `signed_query`.
+    ///
+    /// Make sure to set `CURRENT_OPERATION` before calling this.
     async fn query_inner(
         &self,
         effective_canister_id: Principal,
         signed_query: Vec<u8>,
         request_id: RequestId,
         explicit_verify_query_signatures: Option<bool>,
-        operation: Operation,
     ) -> Result<Vec<u8>, AgentError> {
         let response = if explicit_verify_query_signatures.unwrap_or(self.verify_query_signatures) {
             let (response, mut subnet) = futures_util::try_join!(
-                self.query_endpoint::<QueryResponse>(effective_canister_id, signed_query),
+                self.query_endpoint(effective_canister_id, signed_query),
                 self.get_subnet_by_canister(&effective_canister_id)
             )?;
             if response.signatures().is_empty() {
-                return Err(AgentError::MissingSignature);
+                return Err(ErrorCode::MissingSignature).context(Trust);
             } else if response.signatures().len() > subnet.node_keys.len() {
-                return Err(AgentError::TooManySignatures {
+                return Err(ErrorCode::TooManySignatures {
                     had: response.signatures().len(),
                     needed: subnet.node_keys.len(),
-                });
+                })
+                .context(Protocol);
             }
             for signature in response.signatures() {
                 if OffsetDateTime::now_utc()
                     - OffsetDateTime::from_unix_timestamp_nanos(signature.timestamp.into()).unwrap()
                     > self.ingress_expiry
                 {
-                    return Err(AgentError::CertificateOutdated(self.ingress_expiry));
+                    return Err(ErrorCode::CertificateOutdated(self.ingress_expiry)).context(Trust);
                 }
                 let signable = response.signable(request_id, signature.timestamp);
                 let node_key = if let Some(node_key) = subnet.node_keys.get(&signature.identity) {
@@ -500,38 +526,43 @@ impl Agent {
                     subnet
                         .node_keys
                         .get(&signature.identity)
-                        .ok_or(AgentError::CertificateNotAuthorized())?
+                        .ok_or(ErrorCode::CertificateNotAuthorized)
+                        .context(Trust)?
                 };
                 if node_key.len() != 44 {
-                    return Err(AgentError::DerKeyLengthMismatch {
+                    return Err(ErrorCode::DerKeyLengthMismatch {
                         expected: 44,
                         actual: node_key.len(),
-                    });
+                    })
+                    .context(Protocol);
                 }
                 const DER_PREFIX: [u8; 12] = [48, 42, 48, 5, 6, 3, 43, 101, 112, 3, 33, 0];
                 if node_key[..12] != DER_PREFIX {
-                    return Err(AgentError::DerPrefixMismatch {
+                    return Err(ErrorCode::DerPrefixMismatch {
                         expected: DER_PREFIX.to_vec(),
                         actual: node_key[..12].to_vec(),
-                    });
+                    })
+                    .context(Protocol);
                 }
                 let pubkey =
                     VerificationKey::try_from(<[u8; 32]>::try_from(&node_key[12..]).unwrap())
-                        .map_err(|_| AgentError::MalformedPublicKey)?;
+                        .map_err(|_| ErrorCode::MalformedPublicKey)
+                        .context(Protocol)?;
                 let sig = Signature::from(
                     <[u8; 64]>::try_from(&signature.signature[..])
-                        .map_err(|_| AgentError::MalformedSignature)?,
+                        .map_err(|_| ErrorCode::MalformedSignature)
+                        .context(Protocol)?,
                 );
 
                 match pubkey.verify(&sig, &signable) {
                     Err(Ed25519Error::InvalidSignature) => {
-                        return Err(AgentError::QuerySignatureVerificationFailed)
+                        return Err(ErrorCode::QuerySignatureVerificationFailed).context(Trust)
                     }
                     Err(Ed25519Error::InvalidSliceLength) => {
-                        return Err(AgentError::MalformedSignature)
+                        return Err(ErrorCode::MalformedSignature).context(Protocol)
                     }
                     Err(Ed25519Error::MalformedPublicKey) => {
-                        return Err(AgentError::MalformedPublicKey)
+                        return Err(ErrorCode::MalformedPublicKey).context(Protocol)
                     }
                     Ok(()) => (),
                     _ => unreachable!(),
@@ -539,16 +570,15 @@ impl Agent {
             }
             response
         } else {
-            self.query_endpoint::<QueryResponse>(effective_canister_id, signed_query)
+            self.query_endpoint(effective_canister_id, signed_query)
                 .await?
         };
 
         match response {
             QueryResponse::Replied { reply, .. } => Ok(reply.arg),
-            QueryResponse::Rejected { reject, .. } => Err(AgentError::UncertifiedReject {
-                reject,
-                operation: Some(operation),
-            }),
+            QueryResponse::Rejected { reject, .. } => {
+                Err(ErrorCode::UncertifiedReject { reject }).context(Reject)
+            }
         }
     }
 
@@ -557,20 +587,24 @@ impl Agent {
         canister_id: Principal,
         method_name: String,
         arg: Vec<u8>,
-        ingress_expiry_datetime: Option<u64>,
+        ingress_expiry: u64,
         use_nonce: bool,
     ) -> Result<EnvelopeContent, AgentError> {
         Ok(EnvelopeContent::Query {
-            sender: self.identity.sender().map_err(AgentError::SigningError)?,
+            sender: self
+                .identity
+                .sender()
+                .map_err(ErrorCode::SigningError)
+                .context(External)?,
             canister_id,
             method_name,
             arg,
-            ingress_expiry: ingress_expiry_datetime.unwrap_or_else(|| self.get_expiry_date()),
+            ingress_expiry,
             nonce: use_nonce.then(|| self.nonce_factory.generate()).flatten(),
         })
     }
 
-    /// The simplest way to do an update call; sends a byte array and will return a response, [`CallResponse`], from the replica.
+    /// All update functions except `update_signed` should route through this method.
     async fn update_raw(
         &self,
         canister_id: Principal,
@@ -579,54 +613,84 @@ impl Agent {
         arg: Vec<u8>,
         ingress_expiry_datetime: Option<u64>,
     ) -> Result<CallResponse<(Vec<u8>, Certificate)>, AgentError> {
-        let nonce = self.nonce_factory.generate();
-        let content = self.update_content(
-            canister_id,
-            method_name.clone(),
-            arg,
-            ingress_expiry_datetime,
-            nonce,
-        )?;
-        let operation = Some(Operation::Call {
-            canister: canister_id,
-            method: method_name,
-        });
-        let request_id = to_request_id(&content)?;
-        let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
-
-        let response_body = self
-            .call_endpoint(effective_canister_id, serialized_bytes)
-            .await?;
-
-        match response_body {
-            TransportCallResponse::Replied { certificate } => {
-                let certificate =
-                    serde_cbor::from_slice(&certificate).map_err(AgentError::InvalidCborData)?;
-
-                self.verify(&certificate, effective_canister_id)?;
-                let status = lookup_request_status(&certificate, &request_id)?;
-
-                match status {
-                    RequestStatusResponse::Replied(reply) => {
-                        Ok(CallResponse::Response((reply.arg, certificate)))
+        let expiry = ingress_expiry_datetime.unwrap_or_else(|| self.get_expiry_date());
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                operation: Operation::Update {
+                    canister: canister_id,
+                    method: method_name.clone(),
+                },
+                expiry,
+                response: None,
+                status: OperationStatus::NotSent,
+            },
+            async move {
+                let nonce = self.nonce_factory.generate();
+                let content = self.update_content(
+                    canister_id,
+                    method_name.clone(),
+                    arg,
+                    ingress_expiry_datetime,
+                    nonce,
+                )?;
+
+                let request_id = content.to_request_id();
+                let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
+
+                let response_body = self
+                    .call_endpoint(effective_canister_id, serialized_bytes)
+                    .await?;
+
+                match response_body {
+                    TransportCallResponse::Replied { certificate } => {
+                        let certificate = serde_cbor::from_slice(&certificate).context(Protocol)?;
+
+                        let status =
+                            lookup_request_status(&certificate, &request_id).context(Protocol)?;
+
+                        let tentative_response = match status {
+                            RequestStatusResponse::Replied(reply) => {
+                                try_from_context(&CURRENT_OPERATION, |op| {
+                                    op.response = Some(Ok(reply.arg.clone()))
+                                })
+                                .ok();
+                                Ok(CallResponse::Response((reply.arg, certificate.clone())))
+                            }
+                            RequestStatusResponse::Rejected(reject_response) => {
+                                try_from_context(&CURRENT_OPERATION, |op| {
+                                    op.response = Some(Err(reject_response.clone()))
+                                })
+                                .ok();
+                                Err(ErrorCode::CertifiedReject {
+                                    reject: reject_response,
+                                })
+                                .context(Reject)?
+                            }
+                            _ => Ok(CallResponse::Poll(request_id)),
+                        };
+                        self.verify(&certificate, effective_canister_id)?;
+                        try_from_context(&CURRENT_OPERATION, |op| {
+                            op.status = OperationStatus::Received
+                        })
+                        .ok();
+                        tentative_response
                     }
-                    RequestStatusResponse::Rejected(reject_response) => {
-                        Err(AgentError::CertifiedReject {
+                    TransportCallResponse::Accepted => Ok(CallResponse::Poll(request_id)),
+                    TransportCallResponse::NonReplicatedRejection(reject_response) => {
+                        try_from_context(&CURRENT_OPERATION, |op| {
+                            op.response = Some(Err(reject_response.clone()))
+                        })
+                        .ok();
+                        Err(ErrorCode::UncertifiedReject {
                             reject: reject_response,
-                            operation,
-                        })?
+                        })
+                        .context(Reject)
                     }
-                    _ => Ok(CallResponse::Poll(request_id)),
                 }
-            }
-            TransportCallResponse::Accepted => Ok(CallResponse::Poll(request_id)),
-            TransportCallResponse::NonReplicatedRejection(reject_response) => {
-                Err(AgentError::UncertifiedReject {
-                    reject: reject_response,
-                    operation,
-                })
-            }
-        }
+            },
+        )
+        .await
     }
 
     /// Send the signed update to the network. Will return a [`CallResponse<Vec<u8>>`].
@@ -637,62 +701,91 @@ impl Agent {
         effective_canister_id: Principal,
         signed_update: Vec<u8>,
     ) -> Result<CallResponse<Vec<u8>>, AgentError> {
-        let envelope: Envelope =
-            serde_cbor::from_slice(&signed_update).map_err(AgentError::InvalidCborData)?;
+        let envelope: Envelope = serde_cbor::from_slice(&signed_update).context(Input)?;
         let EnvelopeContent::Call {
             canister_id,
             method_name,
+            ingress_expiry,
             ..
         } = &*envelope.content
         else {
-            return Err(AgentError::CallDataMismatch {
-                field: "request_type".to_string(),
-                value_arg: "update".to_string(),
-                value_cbor: if matches!(*envelope.content, EnvelopeContent::Query { .. }) {
+            return Err(ErrorCode::WrongRequestType {
+                expected: "update".to_string(),
+                found: if matches!(*envelope.content, EnvelopeContent::Query { .. }) {
                     "query"
                 } else {
                     "read_state"
                 }
                 .to_string(),
-            });
+            })
+            .context(Input);
         };
-        let operation = Some(Operation::Call {
-            canister: *canister_id,
-            method: method_name.clone(),
-        });
-        let request_id = to_request_id(&envelope.content)?;
-
-        let response_body = self
-            .call_endpoint(effective_canister_id, signed_update)
-            .await?;
-
-        match response_body {
-            TransportCallResponse::Replied { certificate } => {
-                let certificate =
-                    serde_cbor::from_slice(&certificate).map_err(AgentError::InvalidCborData)?;
-
-                self.verify(&certificate, effective_canister_id)?;
-                let status = lookup_request_status(&certificate, &request_id)?;
-
-                match status {
-                    RequestStatusResponse::Replied(reply) => Ok(CallResponse::Response(reply.arg)),
-                    RequestStatusResponse::Rejected(reject_response) => {
-                        Err(AgentError::CertifiedReject {
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                operation: Operation::Update {
+                    canister: *canister_id,
+                    method: method_name.clone(),
+                },
+                expiry: *ingress_expiry,
+                status: OperationStatus::NotSent,
+                response: None,
+            },
+            async {
+                let request_id = envelope.content.to_request_id();
+
+                let response_body = self
+                    .call_endpoint(effective_canister_id, signed_update)
+                    .await?;
+
+                match response_body {
+                    TransportCallResponse::Replied { certificate } => {
+                        let certificate = serde_cbor::from_slice(&certificate).context(Protocol)?;
+                        let status =
+                            lookup_request_status(&certificate, &request_id).context(Protocol)?;
+
+                        let tentative_response = match status {
+                            RequestStatusResponse::Replied(reply) => {
+                                try_from_context(&CURRENT_OPERATION, |op| {
+                                    op.response = Some(Ok(reply.arg.clone()))
+                                })
+                                .ok();
+                                Ok(CallResponse::Response(reply.arg))
+                            }
+                            RequestStatusResponse::Rejected(reject_response) => {
+                                try_from_context(&CURRENT_OPERATION, |op| {
+                                    op.response = Some(Err(reject_response.clone()))
+                                })
+                                .ok();
+                                Err(ErrorCode::CertifiedReject {
+                                    reject: reject_response,
+                                })
+                                .context(Reject)?
+                            }
+                            _ => Ok(CallResponse::Poll(request_id)),
+                        };
+                        self.verify(&certificate, effective_canister_id)?;
+                        try_from_context(&CURRENT_OPERATION, |op| {
+                            op.status = OperationStatus::Received
+                        })
+                        .ok();
+                        tentative_response
+                    }
+                    TransportCallResponse::Accepted => Ok(CallResponse::Poll(request_id)),
+                    TransportCallResponse::NonReplicatedRejection(reject_response) => {
+                        try_from_context(&CURRENT_OPERATION, |op| {
+                            op.response = Some(Err(reject_response.clone()))
+                        })
+                        .ok();
+                        Err(ErrorCode::UncertifiedReject {
                             reject: reject_response,
-                            operation,
-                        })?
+                        })
+                        .context(Reject)
                     }
-                    _ => Ok(CallResponse::Poll(request_id)),
                 }
-            }
-            TransportCallResponse::Accepted => Ok(CallResponse::Poll(request_id)),
-            TransportCallResponse::NonReplicatedRejection(reject_response) => {
-                Err(AgentError::UncertifiedReject {
-                    reject: reject_response,
-                    operation,
-                })
-            }
-        }
+            },
+        )
+        .await
     }
 
     fn update_content(
@@ -708,7 +801,11 @@ impl Agent {
             method_name,
             arg,
             nonce,
-            sender: self.identity.sender().map_err(AgentError::SigningError)?,
+            sender: self
+                .identity
+                .sender()
+                .map_err(ErrorCode::SigningError)
+                .context(External)?,
             ingress_expiry: ingress_expiry_datetime.unwrap_or_else(|| self.get_expiry_date()),
         })
     }
@@ -755,23 +852,21 @@ impl Agent {
                 }
 
                 RequestStatusResponse::Rejected(response) => {
-                    return Err(AgentError::CertifiedReject {
-                        reject: response,
-                        operation: None,
-                    })
+                    return Err(ErrorCode::CertifiedReject { reject: response }).context(Reject)
                 }
 
                 RequestStatusResponse::Done => {
-                    return Err(AgentError::RequestStatusDoneNoReply(String::from(
+                    return Err(ErrorCode::RequestStatusDoneNoReply(String::from(
                         *request_id,
                     )))
+                    .context(Unknown)
                 }
             };
 
             match retry_policy.next_backoff() {
                 Some(duration) => crate::util::sleep(duration).await,
 
-                None => return Err(AgentError::TimeoutWaitingForResponse()),
+                None => return Err(ErrorCode::TimeoutWaitingForResponse).context(Protocol),
             }
         }
     }
@@ -782,15 +877,13 @@ impl Agent {
         request_id: &RequestId,
         effective_canister_id: Principal,
     ) -> Result<(Vec<u8>, Certificate), AgentError> {
-        self.wait_inner(request_id, effective_canister_id, None)
-            .await
+        self.wait_inner(request_id, effective_canister_id).await
     }
 
     async fn wait_inner(
         &self,
         request_id: &RequestId,
         effective_canister_id: Principal,
-        operation: Option<Operation>,
     ) -> Result<(Vec<u8>, Certificate), AgentError> {
         let mut retry_policy = self.get_retry_policy();
 
@@ -817,27 +910,39 @@ impl Agent {
                 }
 
                 RequestStatusResponse::Replied(ReplyResponse { arg, .. }) => {
-                    return Ok((arg, cert))
+                    try_from_context(&CURRENT_OPERATION, |op| {
+                        op.status = OperationStatus::Received;
+                        op.response = Some(Ok(arg.clone()));
+                    })
+                    .ok();
+                    return Ok((arg, cert));
                 }
 
                 RequestStatusResponse::Rejected(response) => {
-                    return Err(AgentError::CertifiedReject {
-                        reject: response,
-                        operation,
+                    try_from_context(&CURRENT_OPERATION, |op| {
+                        op.status = OperationStatus::Received;
+                        op.response = Some(Err(response.clone()))
                     })
+                    .ok();
+                    return Err(ErrorCode::CertifiedReject { reject: response }).context(Reject);
                 }
 
                 RequestStatusResponse::Done => {
-                    return Err(AgentError::RequestStatusDoneNoReply(String::from(
+                    try_from_context(&CURRENT_OPERATION, |op| {
+                        op.status = OperationStatus::Received
+                    })
+                    .ok();
+                    return Err(ErrorCode::RequestStatusDoneNoReply(String::from(
                         *request_id,
                     )))
+                    .context(Unknown);
                 }
             };
 
             match retry_policy.next_backoff() {
                 Some(duration) => crate::util::sleep(duration).await,
 
-                None => return Err(AgentError::TimeoutWaitingForResponse()),
+                None => return Err(ErrorCode::TimeoutWaitingForResponse).context(Protocol),
             }
         }
     }
@@ -849,16 +954,37 @@ impl Agent {
         paths: Vec<Vec<Label>>,
         effective_canister_id: Principal,
     ) -> Result<Certificate, AgentError> {
-        let content = self.read_state_content(paths)?;
-        let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
-
-        let read_state_response: ReadStateResponse = self
-            .read_state_endpoint(effective_canister_id, serialized_bytes)
-            .await?;
-        let cert: Certificate = serde_cbor::from_slice(&read_state_response.certificate)
-            .map_err(AgentError::InvalidCborData)?;
-        self.verify(&cert, effective_canister_id)?;
-        Ok(cert)
+        // All read_state calls besides request_status_signed should go through this method.
+        let expiry = self.get_expiry_date();
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                status: OperationStatus::NotSent,
+                operation: Operation::ReadState {
+                    paths: paths.clone(),
+                    canister: effective_canister_id,
+                },
+                expiry,
+                response: None,
+            },
+            async {
+                let content = self.read_state_content(paths, expiry)?;
+                let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
+
+                let read_state_response = self
+                    .read_state_endpoint(effective_canister_id, serialized_bytes)
+                    .await?;
+                let cert: Certificate =
+                    serde_cbor::from_slice(&read_state_response.certificate).context(Protocol)?;
+                self.verify(&cert, effective_canister_id)?;
+                try_from_context(&CURRENT_OPERATION, |op| {
+                    op.status = OperationStatus::Received
+                })
+                .ok();
+                Ok(cert)
+            },
+        )
+        .await
     }
 
     /// Request the raw state tree directly, under a subnet ID.
@@ -868,23 +994,52 @@ impl Agent {
         paths: Vec<Vec<Label>>,
         subnet_id: Principal,
     ) -> Result<Certificate, AgentError> {
-        let content = self.read_state_content(paths)?;
-        let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
-
-        let read_state_response: ReadStateResponse = self
-            .read_subnet_state_endpoint(subnet_id, serialized_bytes)
-            .await?;
-        let cert: Certificate = serde_cbor::from_slice(&read_state_response.certificate)
-            .map_err(AgentError::InvalidCborData)?;
-        self.verify_for_subnet(&cert, subnet_id)?;
-        Ok(cert)
+        // All read_subnet_state calls should go through this method.
+        let expiry = self.get_expiry_date();
+        in_context_of(
+            &CURRENT_OPERATION,
+            OperationInfo {
+                status: OperationStatus::NotSent,
+                operation: Operation::ReadSubnetState {
+                    paths: paths.clone(),
+                    subnet: subnet_id,
+                },
+                expiry,
+                response: None,
+            },
+            async {
+                let content = self.read_state_content(paths, expiry)?;
+                let serialized_bytes = sign_envelope(&content, self.identity.clone())?;
+
+                let read_state_response: ReadStateResponse = self
+                    .read_subnet_state_endpoint(subnet_id, serialized_bytes)
+                    .await?;
+                let cert: Certificate =
+                    serde_cbor::from_slice(&read_state_response.certificate).context(Protocol)?;
+                self.verify_for_subnet(&cert, subnet_id)?;
+                try_from_context(&CURRENT_OPERATION, |op| {
+                    op.status = OperationStatus::Received
+                })
+                .ok();
+                Ok(cert)
+            },
+        )
+        .await
     }
 
-    fn read_state_content(&self, paths: Vec<Vec<Label>>) -> Result<EnvelopeContent, AgentError> {
+    fn read_state_content(
+        &self,
+        paths: Vec<Vec<Label>>,
+        ingress_expiry: u64,
+    ) -> Result<EnvelopeContent, AgentError> {
         Ok(EnvelopeContent::ReadState {
-            sender: self.identity.sender().map_err(AgentError::SigningError)?,
+            sender: self
+                .identity
+                .sender()
+                .map_err(ErrorCode::SigningError)
+                .context(External)?,
             paths,
-            ingress_expiry: self.get_expiry_date(),
+            ingress_expiry,
         })
     }
 
@@ -916,7 +1071,8 @@ impl Agent {
         let key = extract_der(der_key)?;
 
         ic_verify_bls_signature::verify_bls_signature(sig, &msg, &key)
-            .map_err(|_| AgentError::CertificateVerificationFailed())?;
+            .map_err(|_| ErrorCode::CertificateVerificationFailed)
+            .context(Trust)?;
         Ok(())
     }
 
@@ -948,18 +1104,19 @@ impl Agent {
         let key = extract_der(der_key)?;
 
         ic_verify_bls_signature::verify_bls_signature(sig, &msg, &key)
-            .map_err(|_| AgentError::CertificateVerificationFailed())?;
+            .map_err(|_| ErrorCode::CertificateVerificationFailed)
+            .context(Trust)?;
         Ok(())
     }
 
     fn verify_cert_timestamp(&self, cert: &Certificate) -> Result<(), AgentError> {
-        let time = lookup_time(cert)?;
+        let time = lookup_time(cert).context(Protocol)?;
         if (OffsetDateTime::now_utc()
             - OffsetDateTime::from_unix_timestamp_nanos(time.into()).unwrap())
         .abs()
             > self.ingress_expiry
         {
-            Err(AgentError::CertificateOutdated(self.ingress_expiry))
+            Err(ErrorCode::CertificateOutdated(self.ingress_expiry)).context(Trust)
         } else {
             Ok(())
         }
@@ -973,10 +1130,10 @@ impl Agent {
         match delegation {
             None => Ok(self.read_root_key()),
             Some(delegation) => {
-                let cert: Certificate = serde_cbor::from_slice(&delegation.certificate)
-                    .map_err(AgentError::InvalidCborData)?;
+                let cert: Certificate =
+                    serde_cbor::from_slice(&delegation.certificate).context(Protocol)?;
                 if cert.delegation.is_some() {
-                    return Err(AgentError::CertificateHasTooManyDelegations);
+                    return Err(ErrorCode::CertificateHasTooManyDelegations).context(Protocol);
                 }
                 self.verify_cert(&cert, effective_canister_id)?;
                 let canister_range_lookup = [
@@ -984,12 +1141,13 @@ impl Agent {
                     delegation.subnet_id.as_ref(),
                     "canister_ranges".as_bytes(),
                 ];
-                let canister_range = lookup_value(&cert.tree, canister_range_lookup)?;
+                let canister_range =
+                    lookup_value(&cert.tree, canister_range_lookup).context(Protocol)?;
                 let ranges: Vec<(Principal, Principal)> =
-                    serde_cbor::from_slice(canister_range).map_err(AgentError::InvalidCborData)?;
+                    serde_cbor::from_slice(canister_range).context(Protocol)?;
                 if !principal_is_within_ranges(&effective_canister_id, &ranges[..]) {
                     // the certificate is not authorized to answer calls for this canister
-                    return Err(AgentError::CertificateNotAuthorized());
+                    return Err(ErrorCode::CertificateNotAuthorized).context(Trust);
                 }
 
                 let public_key_path = [
@@ -997,7 +1155,9 @@ impl Agent {
                     delegation.subnet_id.as_ref(),
                     "public_key".as_bytes(),
                 ];
-                lookup_value(&cert.tree, public_key_path).map(<[u8]>::to_vec)
+                lookup_value(&cert.tree, public_key_path)
+                    .map(<[u8]>::to_vec)
+                    .context(Protocol)
             }
         }
     }
@@ -1010,10 +1170,10 @@ impl Agent {
         match delegation {
             None => Ok(self.read_root_key()),
             Some(delegation) => {
-                let cert: Certificate = serde_cbor::from_slice(&delegation.certificate)
-                    .map_err(AgentError::InvalidCborData)?;
+                let cert: Certificate =
+                    serde_cbor::from_slice(&delegation.certificate).context(Protocol)?;
                 if cert.delegation.is_some() {
-                    return Err(AgentError::CertificateHasTooManyDelegations);
+                    return Err(ErrorCode::CertificateHasTooManyDelegations).context(Protocol);
                 }
                 self.verify_cert_for_subnet(&cert, subnet_id)?;
                 let public_key_path = [
@@ -1022,7 +1182,8 @@ impl Agent {
                     "public_key".as_bytes(),
                 ];
                 let pk = lookup_value(&cert.tree, public_key_path)
-                    .map_err(|_| AgentError::CertificateNotAuthorized())?
+                    .map_err(|_| ErrorCode::CertificateNotAuthorized)
+                    .context(Trust)?
                     .to_vec();
                 Ok(pk)
             }
@@ -1035,7 +1196,7 @@ impl Agent {
         &self,
         canister_id: Principal,
         path: &str,
-    ) -> Result<Vec<u8>, AgentError> {
+    ) -> Result<Option<Vec<u8>>, AgentError> {
         let paths: Vec<Vec<Label>> = vec![vec![
             "canister".into(),
             Label::from_bytes(canister_id.as_slice()),
@@ -1044,37 +1205,44 @@ impl Agent {
 
         let cert = self.read_state_raw(paths, canister_id).await?;
 
-        lookup_canister_info(cert, canister_id, path)
+        let lookup_res = lookup_canister_info(cert, canister_id, path);
+        if let Err(LookupError::Absent { .. }) = &lookup_res {
+            Ok(None)
+        } else {
+            lookup_res.map(Some).context(Protocol)
+        }
     }
 
-    /// Request the controller list of a given canister.
+    /// Request the controller list of a given canister, or `None` if the canister does not exist.
     pub async fn read_state_canister_controllers(
         &self,
         canister_id: Principal,
-    ) -> Result<Vec<Principal>, AgentError> {
-        let blob = self
+    ) -> Result<Option<Vec<Principal>>, AgentError> {
+        let Some(blob) = self
             .read_state_canister_info(canister_id, "controllers")
-            .await?;
-        let controllers: Vec<Principal> =
-            serde_cbor::from_slice(&blob).map_err(AgentError::InvalidCborData)?;
-        Ok(controllers)
+            .await?
+        else {
+            return Ok(None);
+        };
+        let controllers: Vec<Principal> = serde_cbor::from_slice(&blob).context(Protocol)?;
+        Ok(Some(controllers))
     }
 
-    /// Request the module hash of a given canister.
+    /// Request the module hash of a given canister, or `None` if the canister is empty or does not exist.
     pub async fn read_state_canister_module_hash(
         &self,
         canister_id: Principal,
-    ) -> Result<Vec<u8>, AgentError> {
+    ) -> Result<Option<Vec<u8>>, AgentError> {
         self.read_state_canister_info(canister_id, "module_hash")
             .await
     }
 
-    /// Request the bytes of the canister's custom section `icp:public <path>` or `icp:private <path>`.
+    /// Request the bytes of the canister's custom section `icp:public <path>` or `icp:private <path>`, or `None` if it does not exist.
     pub async fn read_state_canister_metadata(
         &self,
         canister_id: Principal,
         path: &str,
-    ) -> Result<Vec<u8>, AgentError> {
+    ) -> Result<Option<Vec<u8>>, AgentError> {
         let paths: Vec<Vec<Label>> = vec![vec![
             "canister".into(),
             Label::from_bytes(canister_id.as_slice()),
@@ -1084,7 +1252,12 @@ impl Agent {
 
         let cert = self.read_state_raw(paths, canister_id).await?;
 
-        lookup_canister_metadata(cert, canister_id, path)
+        let lookup_res = lookup_canister_metadata(cert, canister_id, path);
+        if let Err(LookupError::Absent { .. }) = &lookup_res {
+            Ok(None)
+        } else {
+            lookup_res.map(Some).context(Protocol)
+        }
     }
 
     /// Request a list of metrics about the subnet.
@@ -1098,7 +1271,7 @@ impl Agent {
             "metrics".into(),
         ]];
         let cert = self.read_subnet_state_raw(paths, subnet_id).await?;
-        lookup_subnet_metrics(cert, subnet_id)
+        lookup_subnet_metrics(cert, subnet_id).context(Protocol)
     }
 
     /// Fetches the status of a particular request by its ID.
@@ -1112,7 +1285,10 @@ impl Agent {
 
         let cert = self.read_state_raw(paths, effective_canister_id).await?;
 
-        Ok((lookup_request_status(&cert, request_id)?, cert))
+        Ok((
+            lookup_request_status(&cert, request_id).context(Protocol)?,
+            cert,
+        ))
     }
 
     /// Send the signed `request_status` to the network. Will return [`RequestStatusResponse`].
@@ -1124,16 +1300,18 @@ impl Agent {
         effective_canister_id: Principal,
         signed_request_status: Vec<u8>,
     ) -> Result<(RequestStatusResponse, Certificate), AgentError> {
-        let _envelope: Envelope =
-            serde_cbor::from_slice(&signed_request_status).map_err(AgentError::InvalidCborData)?;
+        let _envelope: Envelope = serde_cbor::from_slice(&signed_request_status).context(Input)?;
         let read_state_response: ReadStateResponse = self
             .read_state_endpoint(effective_canister_id, signed_request_status)
             .await?;
 
-        let cert: Certificate = serde_cbor::from_slice(&read_state_response.certificate)
-            .map_err(AgentError::InvalidCborData)?;
+        let cert: Certificate =
+            serde_cbor::from_slice(&read_state_response.certificate).context(Protocol)?;
         self.verify(&cert, effective_canister_id)?;
-        Ok((lookup_request_status(&cert, request_id)?, cert))
+        Ok((
+            lookup_request_status(&cert, request_id).context(Protocol)?,
+            cert,
+        ))
     }
 
     /// Returns an `UpdateBuilder` enabling the construction of an update call without
@@ -1151,10 +1329,11 @@ impl Agent {
         let endpoint = "api/v2/status";
         let bytes = self.execute(Method::GET, endpoint, None).await?.1;
 
-        let cbor: serde_cbor::Value =
-            serde_cbor::from_slice(&bytes).map_err(AgentError::InvalidCborData)?;
+        let cbor: serde_cbor::Value = serde_cbor::from_slice(&bytes).context(Protocol)?;
 
-        Status::try_from(&cbor).map_err(|_| AgentError::InvalidReplicaStatus)
+        Status::try_from(&cbor)
+            .map_err(|_| ErrorCode::InvalidReplicaStatus)
+            .context(Protocol)
     }
 
     /// Returns a `QueryBuilder` enabling the construction of a query call without
@@ -1172,7 +1351,8 @@ impl Agent {
     ) -> Result<SignedRequestStatus, AgentError> {
         let paths: Vec<Vec<Label>> =
             vec![vec!["request_status".into(), request_id.to_vec().into()]];
-        let read_state_content = self.read_state_content(paths)?;
+        let expiry = self.get_expiry_date();
+        let read_state_content = self.read_state_content(paths, expiry)?;
         let signed_request_status = sign_envelope(&read_state_content, self.identity.clone())?;
         let ingress_expiry = read_state_content.ingress_expiry();
         let sender = *read_state_content.sender();
@@ -1208,7 +1388,7 @@ impl Agent {
     ) -> Result<Vec<ApiBoundaryNode>, AgentError> {
         let paths = vec![vec!["api_boundary_nodes".into()]];
         let certificate = self.read_state_raw(paths, canister_id).await?;
-        let api_boundary_nodes = lookup_api_boundary_nodes(certificate)?;
+        let api_boundary_nodes = lookup_api_boundary_nodes(certificate).context(Protocol)?;
         Ok(api_boundary_nodes)
     }
 
@@ -1219,7 +1399,7 @@ impl Agent {
     ) -> Result<Vec<ApiBoundaryNode>, AgentError> {
         let paths = vec![vec!["api_boundary_nodes".into()]];
         let certificate = self.read_subnet_state_raw(paths, subnet_id).await?;
-        let api_boundary_nodes = lookup_api_boundary_nodes(certificate)?;
+        let api_boundary_nodes = lookup_api_boundary_nodes(certificate).context(Protocol)?;
         Ok(api_boundary_nodes)
     }
 
@@ -1240,6 +1420,16 @@ impl Agent {
         Ok(subnet)
     }
 
+    fn route(&self) -> Result<Url, AgentError> {
+        match self.route_provider.route() {
+            Ok(route) => Ok(route),
+            Err(mut err) => {
+                err.add_context();
+                Err(err)
+            }
+        }
+    }
+
     async fn request(
         &self,
         method: Method,
@@ -1247,7 +1437,7 @@ impl Agent {
         body: Option<Vec<u8>>,
     ) -> Result<(StatusCode, HeaderMap, Vec<u8>), AgentError> {
         let create_request_with_generated_url = || -> Result<Request, AgentError> {
-            let url = self.route_provider.route()?.join(endpoint)?;
+            let url = self.route()?.join(endpoint).context(Input)?;
             let mut http_request = Request::new(method.clone(), url);
             http_request
                 .headers_mut()
@@ -1256,13 +1446,20 @@ impl Agent {
             Ok(http_request)
         };
 
+        try_from_context(&CURRENT_OPERATION, |op| {
+            if op.status == OperationStatus::NotSent {
+                op.status = OperationStatus::MaybeReceived;
+            }
+        })
+        .ok();
         let response = self
             .client
             .call(
                 &create_request_with_generated_url,
                 self.max_tcp_error_retries,
             )
-            .await?;
+            .await
+            .map_err(|e| AgentError::from_boxed_in_context(e, Transport))?;
 
         let http_status = response.status();
         let response_headers = response.headers().clone();
@@ -1272,7 +1469,7 @@ impl Agent {
             .max_response_body_size
             .zip(response.content_length()), Some((size_limit, content_length)) if content_length > size_limit as u64)
         {
-            return Err(AgentError::ResponseSizeExceededLimit());
+            return Err(ErrorCode::ResponseSizeExceededLimit).context(Limit);
         }
 
         let mut body: Vec<u8> = response
@@ -1282,13 +1479,13 @@ impl Agent {
         let mut stream = response.bytes_stream();
 
         while let Some(chunk) = stream.next().await {
-            let chunk = chunk?;
+            let chunk = chunk.context(Transport)?;
 
             // Size Check (Body Size)
             if matches!(self
                 .max_response_body_size, Some(size_limit) if body.len() + chunk.len() > size_limit)
             {
-                return Err(AgentError::ResponseSizeExceededLimit());
+                return Err(ErrorCode::ResponseSizeExceededLimit).context(Limit);
             }
 
             body.extend_from_slice(chunk.as_ref());
@@ -1310,18 +1507,20 @@ impl Agent {
         let body = request_result.2;
 
         if status.is_client_error() || status.is_server_error() {
-            Err(AgentError::HttpError(HttpErrorPayload {
+            Err(HttpErrorPayload {
                 status: status.into(),
                 content_type: headers
                     .get(CONTENT_TYPE)
                     .and_then(|value| value.to_str().ok())
                     .map(str::to_string),
                 content: body,
-            }))
+            })
+            .context(Protocol)
         } else if !(status == StatusCode::OK || status == StatusCode::ACCEPTED) {
-            Err(AgentError::InvalidHttpResponse(format!(
+            Err(ErrorCode::InvalidHttpResponse(format!(
                 "Expected `200`, `202`, 4xx`, or `5xx` HTTP status code. Got: {status}",
             )))
+            .context(Protocol)
         } else {
             Ok((status, body))
         }
@@ -1340,7 +1539,10 @@ fn sign_envelope(
     content: &EnvelopeContent,
     identity: Arc<dyn Identity>,
 ) -> Result<Vec<u8>, AgentError> {
-    let signature = identity.sign(content).map_err(AgentError::SigningError)?;
+    let signature = identity
+        .sign(content)
+        .map_err(ErrorCode::SigningError)
+        .context(External)?;
 
     let envelope = Envelope {
         content: Cow::Borrowed(content),
@@ -1349,12 +1551,7 @@ fn sign_envelope(
         sender_delegation: signature.delegations,
     };
 
-    let mut serialized_bytes = Vec::new();
-    let mut serializer = serde_cbor::Serializer::new(&mut serialized_bytes);
-    serializer.self_describe()?;
-    envelope.serialize(&mut serializer)?;
-
-    Ok(serialized_bytes)
+    Ok(envelope.encode_bytes())
 }
 
 /// Inspect the bytes to be sent as a query
@@ -1366,9 +1563,10 @@ pub fn signed_query_inspect(
     arg: &[u8],
     ingress_expiry: u64,
     signed_query: Vec<u8>,
-) -> Result<(), AgentError> {
-    let envelope: Envelope =
-        serde_cbor::from_slice(&signed_query).map_err(AgentError::InvalidCborData)?;
+) -> Result<(), InspectionError> {
+    let envelope: Envelope = serde_cbor::from_slice(&signed_query)
+        .context(Input)
+        .map_err(InspectionError::Other)?;
     match envelope.content.as_ref() {
         EnvelopeContent::Query {
             ingress_expiry: ingress_expiry_cbor,
@@ -1379,35 +1577,35 @@ pub fn signed_query_inspect(
             nonce: _nonce,
         } => {
             if ingress_expiry != *ingress_expiry_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "ingress_expiry".to_string(),
                     value_arg: ingress_expiry.to_string(),
                     value_cbor: ingress_expiry_cbor.to_string(),
                 });
             }
             if sender != *sender_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "sender".to_string(),
                     value_arg: sender.to_string(),
                     value_cbor: sender_cbor.to_string(),
                 });
             }
             if canister_id != *canister_id_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "canister_id".to_string(),
                     value_arg: canister_id.to_string(),
                     value_cbor: canister_id_cbor.to_string(),
                 });
             }
             if method_name != *method_name_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "method_name".to_string(),
                     value_arg: method_name.to_string(),
                     value_cbor: method_name_cbor.clone(),
                 });
             }
             if arg != *arg_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "arg".to_string(),
                     value_arg: format!("{arg:?}"),
                     value_cbor: format!("{arg_cbor:?}"),
@@ -1415,18 +1613,18 @@ pub fn signed_query_inspect(
             }
         }
         EnvelopeContent::Call { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "query".to_string(),
                 value_cbor: "call".to_string(),
-            })
+            });
         }
         EnvelopeContent::ReadState { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "query".to_string(),
                 value_cbor: "read_state".to_string(),
-            })
+            });
         }
     }
     Ok(())
@@ -1441,9 +1639,10 @@ pub fn signed_update_inspect(
     arg: &[u8],
     ingress_expiry: u64,
     signed_update: Vec<u8>,
-) -> Result<(), AgentError> {
-    let envelope: Envelope =
-        serde_cbor::from_slice(&signed_update).map_err(AgentError::InvalidCborData)?;
+) -> Result<(), InspectionError> {
+    let envelope: Envelope = serde_cbor::from_slice(&signed_update)
+        .context(Input)
+        .map_err(InspectionError::Other)?;
     match envelope.content.as_ref() {
         EnvelopeContent::Call {
             nonce: _nonce,
@@ -1454,35 +1653,35 @@ pub fn signed_update_inspect(
             arg: arg_cbor,
         } => {
             if ingress_expiry != *ingress_expiry_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "ingress_expiry".to_string(),
                     value_arg: ingress_expiry.to_string(),
                     value_cbor: ingress_expiry_cbor.to_string(),
                 });
             }
             if sender != *sender_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "sender".to_string(),
                     value_arg: sender.to_string(),
                     value_cbor: sender_cbor.to_string(),
                 });
             }
             if canister_id != *canister_id_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "canister_id".to_string(),
                     value_arg: canister_id.to_string(),
                     value_cbor: canister_id_cbor.to_string(),
                 });
             }
             if method_name != *method_name_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "method_name".to_string(),
                     value_arg: method_name.to_string(),
                     value_cbor: method_name_cbor.clone(),
                 });
             }
             if arg != *arg_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "arg".to_string(),
                     value_arg: format!("{arg:?}"),
                     value_cbor: format!("{arg_cbor:?}"),
@@ -1490,18 +1689,18 @@ pub fn signed_update_inspect(
             }
         }
         EnvelopeContent::ReadState { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "call".to_string(),
                 value_cbor: "read_state".to_string(),
-            })
+            });
         }
         EnvelopeContent::Query { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "call".to_string(),
                 value_cbor: "query".to_string(),
-            })
+            });
         }
     }
     Ok(())
@@ -1514,10 +1713,11 @@ pub fn signed_request_status_inspect(
     request_id: &RequestId,
     ingress_expiry: u64,
     signed_request_status: Vec<u8>,
-) -> Result<(), AgentError> {
+) -> Result<(), InspectionError> {
     let paths: Vec<Vec<Label>> = vec![vec!["request_status".into(), request_id.to_vec().into()]];
-    let envelope: Envelope =
-        serde_cbor::from_slice(&signed_request_status).map_err(AgentError::InvalidCborData)?;
+    let envelope: Envelope = serde_cbor::from_slice(&signed_request_status)
+        .context(Input)
+        .map_err(InspectionError::Other)?;
     match envelope.content.as_ref() {
         EnvelopeContent::ReadState {
             ingress_expiry: ingress_expiry_cbor,
@@ -1525,14 +1725,14 @@ pub fn signed_request_status_inspect(
             paths: paths_cbor,
         } => {
             if ingress_expiry != *ingress_expiry_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "ingress_expiry".to_string(),
                     value_arg: ingress_expiry.to_string(),
                     value_cbor: ingress_expiry_cbor.to_string(),
                 });
             }
             if sender != *sender_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "sender".to_string(),
                     value_arg: sender.to_string(),
                     value_cbor: sender_cbor.to_string(),
@@ -1540,7 +1740,7 @@ pub fn signed_request_status_inspect(
             }
 
             if paths != *paths_cbor {
-                return Err(AgentError::CallDataMismatch {
+                return Err(InspectionError::CallDataMismatch {
                     field: "paths".to_string(),
                     value_arg: format!("{paths:?}"),
                     value_cbor: format!("{paths_cbor:?}"),
@@ -1548,18 +1748,18 @@ pub fn signed_request_status_inspect(
             }
         }
         EnvelopeContent::Query { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "read_state".to_string(),
                 value_cbor: "query".to_string(),
-            })
+            });
         }
         EnvelopeContent::Call { .. } => {
-            return Err(AgentError::CallDataMismatch {
+            return Err(InspectionError::CallDataMismatch {
                 field: "request_type".to_string(),
                 value_arg: "read_state".to_string(),
                 value_cbor: "call".to_string(),
-            })
+            });
         }
     }
     Ok(())
@@ -1801,7 +2001,8 @@ impl<'agent> QueryBuilder<'agent> {
             self.canister_id,
             self.method_name,
             self.arg,
-            self.ingress_expiry_datetime,
+            self.ingress_expiry_datetime
+                .unwrap_or_else(|| self.agent.get_expiry_date()),
             self.use_nonce,
         )
     }
@@ -1820,8 +2021,6 @@ pub struct UpdateCall<'agent> {
     agent: &'agent Agent,
     response_future: AgentFuture<'agent, CallResponse<(Vec<u8>, Certificate)>>,
     effective_canister_id: Principal,
-    canister_id: Principal,
-    method_name: String,
 }
 
 impl fmt::Debug for UpdateCall<'_> {
@@ -1849,14 +2048,7 @@ impl<'a> UpdateCall<'a> {
             CallResponse::Response(response) => Ok(response),
             CallResponse::Poll(request_id) => {
                 self.agent
-                    .wait_inner(
-                        &request_id,
-                        self.effective_canister_id,
-                        Some(Operation::Call {
-                            canister: self.canister_id,
-                            method: self.method_name,
-                        }),
-                    )
+                    .wait_inner(&request_id, self.effective_canister_id)
                     .await
             }
         }
@@ -1931,7 +2123,6 @@ impl<'agent> UpdateBuilder<'agent> {
     /// Make an update call. This will return a `RequestId`.
     /// The `RequestId` should then be used for `request_status` (most likely in a loop).
     pub fn call(self) -> UpdateCall<'agent> {
-        let method_name = self.method_name.clone();
         let response_future = async move {
             self.agent
                 .update_raw(
@@ -1947,8 +2138,6 @@ impl<'agent> UpdateBuilder<'agent> {
             agent: self.agent,
             response_future: Box::pin(response_future),
             effective_canister_id: self.effective_canister_id,
-            canister_id: self.canister_id,
-            method_name,
         }
     }
 
@@ -1959,7 +2148,7 @@ impl<'agent> UpdateBuilder<'agent> {
         let effective_canister_id = self.effective_canister_id;
         let content = self.into_envelope()?;
         let signed_update = sign_envelope(&content, identity)?;
-        let request_id = to_request_id(&content)?;
+        let request_id = content.to_request_id();
         let EnvelopeContent::Call {
             nonce,
             ingress_expiry,
@@ -2014,7 +2203,7 @@ pub trait HttpService: Send + Sync + Debug {
         &'a self,
         req: &'a (dyn Fn() -> Result<Request, AgentError> + Send + Sync),
         max_retries: usize,
-    ) -> Result<Response, AgentError>;
+    ) -> Result<Response, Box<dyn Error + Send + Sync>>;
 }
 #[cfg(not(target_family = "wasm"))]
 #[async_trait]
@@ -2029,7 +2218,7 @@ where
         mut self: &'a Self,
         req: &'a (dyn Fn() -> Result<Request, AgentError> + Send + Sync),
         max_retries: usize,
-    ) -> Result<Response, AgentError> {
+    ) -> Result<Response, Box<dyn Error + Send + Sync>> {
         let mut retry_count = 0;
         loop {
             match Service::call(&mut self, req()?).await {
@@ -2037,7 +2226,7 @@ where
                     // Network-related errors can be retried.
                     if err.is_connect() {
                         if retry_count >= max_retries {
-                            return Err(AgentError::TransportError(err));
+                            return Err(err.into());
                         }
                         retry_count += 1;
                     }
@@ -2060,7 +2249,7 @@ where
         mut self: &'a Self,
         req: &'a (dyn Fn() -> Result<Request, AgentError> + Send + Sync),
         _: usize,
-    ) -> Result<Response, AgentError> {
+    ) -> Result<Response, Box<dyn Error + Send + Sync>> {
         Ok(Service::call(&mut self, req()?).await?)
     }
 }
@@ -2077,7 +2266,7 @@ impl HttpService for Retry429Logic {
         &'a self,
         req: &'a (dyn Fn() -> Result<Request, AgentError> + Send + Sync),
         _max_tcp_retries: usize,
-    ) -> Result<Response, AgentError> {
+    ) -> Result<Response, Box<dyn Error + Send + Sync>> {
         let mut retries = 0;
         loop {
             #[cfg(not(target_family = "wasm"))]
@@ -2100,6 +2289,82 @@ impl HttpService for Retry429Logic {
     }
 }
 
+/// The status of an [`Operation`].
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub enum OperationStatus {
+    /// The operation has not been sent to the IC.
+    NotSent,
+    /// The operation may or may not have been sent to the IC, and the IC may or may not have received it.
+    MaybeReceived,
+    /// The IC has definitely received the request, and any further information is certified.
+    /// This is never returned for query calls.
+    Received,
+}
+
+/// Info about an agent operation. Can be obtained from [`AgentError`].
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct OperationInfo {
+    /// The known status of the operation. Only set to [`Received`] if this is *guaranteed* to be true.
+    pub status: OperationStatus,
+    /// The operation being attempted.
+    pub operation: Operation,
+    /// The expiry timestamp of the operation, in Unix nanoseconds.
+    pub expiry: u64,
+    /// The response to the operation, if it has been completed. The result is `Ok` for responses and `Err` for rejects.
+    ///
+    /// This information is reliable if-and-only-if `status` is set to [`Received`].
+    pub response: Option<Result<Vec<u8>, RejectResponse>>,
+}
+
+impl OperationInfo {
+    /// Convenience wrapper for borrowing `response`.
+    pub fn response(&self) -> Option<Result<&[u8], &RejectResponse>> {
+        match &self.response {
+            Some(Ok(o)) => Some(Ok(o)),
+            Some(Err(e)) => Some(Err(e)),
+            None => None,
+        }
+    }
+}
+
+/// An operation that can result in a reject.
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum Operation {
+    /// A certified call to a canister method.
+    Update {
+        /// The canister whose method was called.
+        canister: Principal,
+        /// The name of the method.
+        method: String,
+    },
+    /// A query call to a canister method.
+    Query {
+        /// The canister whose method was called.
+        canister: Principal,
+        /// The name of the method.
+        method: String,
+    },
+    /// A read of the state tree, in the context of a canister. This will *not* be the active operation during request polling.
+    ReadState {
+        /// The requested paths within the state tree.
+        paths: Vec<Vec<Label>>,
+        /// The canister the read request was made in the context of.
+        canister: Principal,
+    },
+    /// A read of the state tree, in the context of a subnet.
+    ReadSubnetState {
+        /// The requested paths within the state tree.
+        paths: Vec<Vec<Label>>,
+        /// The subnet the read request was made in the context of.
+        subnet: Principal,
+    },
+}
+
+task_local! {
+    static CURRENT_OPERATION: OperationInfo;
+}
+
 #[cfg(all(test, not(target_family = "wasm")))]
 mod offline_tests {
     use super::*;
diff --git a/ic-agent/src/agent/response_authentication.rs b/ic-agent/src/agent/response_authentication.rs
index 4a50a18b..375c2a27 100644
--- a/ic-agent/src/agent/response_authentication.rs
+++ b/ic-agent/src/agent/response_authentication.rs
@@ -1,11 +1,21 @@
-use crate::agent::{ApiBoundaryNode, RejectCode, RejectResponse, RequestStatusResponse};
-use crate::{export::Principal, AgentError, RequestId};
+use crate::agent::{
+    agent_error::{AgentError, ErrorCode, ErrorKind::*, ResultExt as _},
+    ApiBoundaryNode, RejectCode, RejectResponse, RequestStatusResponse,
+};
+use crate::{export::Principal, RequestId};
 use ic_certification::hash_tree::{HashTree, SubtreeLookupResult};
 use ic_certification::{certificate::Certificate, hash_tree::Label, LookupResult};
 use ic_transport_types::{ReplyResponse, SubnetMetrics};
+use itertools::Itertools;
 use rangemap::RangeInclusiveSet;
-use std::collections::{HashMap, HashSet};
-use std::str::from_utf8;
+use std::{
+    collections::{HashMap, HashSet},
+    error::Error,
+};
+use std::{
+    fmt::{Display, Formatter},
+    str::from_utf8,
+};
 
 use super::Subnet;
 
@@ -15,18 +25,20 @@ const KEY_LENGTH: usize = 96;
 pub fn extract_der(buf: Vec<u8>) -> Result<Vec<u8>, AgentError> {
     let expected_length = DER_PREFIX.len() + KEY_LENGTH;
     if buf.len() != expected_length {
-        return Err(AgentError::DerKeyLengthMismatch {
+        return Err(ErrorCode::DerKeyLengthMismatch {
             expected: expected_length,
             actual: buf.len(),
-        });
+        })
+        .context(Protocol);
     }
 
     let prefix = &buf[0..DER_PREFIX.len()];
     if prefix[..] != DER_PREFIX[..] {
-        return Err(AgentError::DerPrefixMismatch {
+        return Err(ErrorCode::DerPrefixMismatch {
             expected: DER_PREFIX.to_vec(),
             actual: prefix.to_vec(),
-        });
+        })
+        .context(Protocol);
     }
 
     let key = &buf[DER_PREFIX.len()..];
@@ -35,16 +47,17 @@ pub fn extract_der(buf: Vec<u8>) -> Result<Vec<u8>, AgentError> {
 
 pub(crate) fn lookup_time<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
-) -> Result<u64, AgentError> {
-    let mut time = lookup_value(&certificate.tree, ["time".as_bytes()])?;
-    Ok(leb128::read::unsigned(&mut time)?)
+) -> Result<u64, LookupError> {
+    let path = ["time".as_bytes()];
+    let mut time = lookup_value(&certificate.tree, path)?;
+    leb128::read::unsigned(&mut time).context_deserialize(path)
 }
 
 pub(crate) fn lookup_canister_info<Storage: AsRef<[u8]>>(
     certificate: Certificate<Storage>,
     canister_id: Principal,
     path: &str,
-) -> Result<Vec<u8>, AgentError> {
+) -> Result<Vec<u8>, LookupError> {
     let path_canister = [
         "canister".as_bytes(),
         canister_id.as_slice(),
@@ -57,7 +70,7 @@ pub(crate) fn lookup_canister_metadata<Storage: AsRef<[u8]>>(
     certificate: Certificate<Storage>,
     canister_id: Principal,
     path: &str,
-) -> Result<Vec<u8>, AgentError> {
+) -> Result<Vec<u8>, LookupError> {
     let path_canister = [
         "canister".as_bytes(),
         canister_id.as_slice(),
@@ -71,17 +84,16 @@ pub(crate) fn lookup_canister_metadata<Storage: AsRef<[u8]>>(
 pub(crate) fn lookup_subnet_metrics<Storage: AsRef<[u8]>>(
     certificate: Certificate<Storage>,
     subnet_id: Principal,
-) -> Result<SubnetMetrics, AgentError> {
+) -> Result<SubnetMetrics, LookupError> {
     let path_stats = [b"subnet", subnet_id.as_slice(), b"metrics"];
     let metrics = lookup_value(&certificate.tree, path_stats)?;
-    Ok(serde_cbor::from_slice(metrics)?)
+    serde_cbor::from_slice(metrics).context_deserialize(path_stats)
 }
 
 pub(crate) fn lookup_request_status<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<RequestStatusResponse, AgentError> {
-    use AgentError::*;
+) -> Result<RequestStatusResponse, LookupError> {
     let path_status = [
         "request_status".into(),
         request_id.to_vec().into(),
@@ -89,23 +101,32 @@ pub(crate) fn lookup_request_status<Storage: AsRef<[u8]>>(
     ];
     match certificate.tree.lookup_path(&path_status) {
         LookupResult::Absent => Ok(RequestStatusResponse::Unknown),
-        LookupResult::Unknown => Err(LookupPathUnknown(path_status.to_vec())),
-        LookupResult::Found(status) => match from_utf8(status)? {
-            "done" => Ok(RequestStatusResponse::Done),
-            "processing" => Ok(RequestStatusResponse::Processing),
-            "received" => Ok(RequestStatusResponse::Received),
-            "rejected" => lookup_rejection(certificate, request_id),
-            "replied" => lookup_reply(certificate, request_id),
-            other => Err(InvalidRequestStatus(path_status.into(), other.to_string())),
-        },
-        LookupResult::Error => Err(LookupPathError(path_status.into())),
+        LookupResult::Unknown => Err(LookupError::Unacknowledged {
+            path: path_status.to_vec(),
+        }),
+        LookupResult::Found(status) => {
+            match from_utf8(status).context_deserialize(&path_status[..])? {
+                "done" => Ok(RequestStatusResponse::Done),
+                "processing" => Ok(RequestStatusResponse::Processing),
+                "received" => Ok(RequestStatusResponse::Received),
+                "rejected" => lookup_rejection(certificate, request_id),
+                "replied" => lookup_reply(certificate, request_id),
+                other => Err(LookupError::Deserialize {
+                    path: path_status.into_vec(),
+                    source: Box::new(InvalidRequestStatusError(other.to_string())),
+                }),
+            }
+        }
+        LookupResult::Error => Err(LookupError::Malformed {
+            path: path_status.into_vec(),
+        }),
     }
 }
 
 pub(crate) fn lookup_rejection<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<RequestStatusResponse, AgentError> {
+) -> Result<RequestStatusResponse, LookupError> {
     let reject_code = lookup_reject_code(certificate, request_id)?;
     let reject_message = lookup_reject_message(certificate, request_id)?;
     let error_code = lookup_error_code(certificate, request_id)?;
@@ -120,7 +141,7 @@ pub(crate) fn lookup_rejection<Storage: AsRef<[u8]>>(
 pub(crate) fn lookup_reject_code<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<RejectCode, AgentError> {
+) -> Result<RejectCode, LookupError> {
     let path = [
         "request_status".as_bytes(),
         request_id.as_slice(),
@@ -128,27 +149,27 @@ pub(crate) fn lookup_reject_code<Storage: AsRef<[u8]>>(
     ];
     let code = lookup_value(&certificate.tree, path)?;
     let mut readable = code;
-    let code_digit = leb128::read::unsigned(&mut readable)?;
-    Ok(RejectCode::try_from(code_digit)?)
+    let code_digit = leb128::read::unsigned(&mut readable).context_deserialize(path)?;
+    RejectCode::try_from(code_digit).context_deserialize(path)
 }
 
 pub(crate) fn lookup_reject_message<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<String, AgentError> {
+) -> Result<String, LookupError> {
     let path = [
         "request_status".as_bytes(),
         request_id.as_slice(),
         "reject_message".as_bytes(),
     ];
     let msg = lookup_value(&certificate.tree, path)?;
-    Ok(from_utf8(msg)?.to_string())
+    Ok(from_utf8(msg).context_deserialize(path)?.to_string())
 }
 
 pub(crate) fn lookup_error_code<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<Option<String>, AgentError> {
+) -> Result<Option<String>, LookupError> {
     let path = [
         "request_status".as_bytes(),
         request_id.as_slice(),
@@ -156,8 +177,8 @@ pub(crate) fn lookup_error_code<Storage: AsRef<[u8]>>(
     ];
     let msg = lookup_value(&certificate.tree, path);
     match msg {
-        Ok(val) => Ok(Some(from_utf8(val)?.to_string())),
-        Err(AgentError::LookupPathAbsent(_)) => Ok(None),
+        Ok(val) => Ok(Some(from_utf8(val).context_deserialize(path)?.to_string())),
+        Err(LookupError::Absent { .. }) => Ok(None),
         Err(e) => Err(e),
     }
 }
@@ -165,7 +186,7 @@ pub(crate) fn lookup_error_code<Storage: AsRef<[u8]>>(
 pub(crate) fn lookup_reply<Storage: AsRef<[u8]>>(
     certificate: &Certificate<Storage>,
     request_id: &RequestId,
-) -> Result<RequestStatusResponse, AgentError> {
+) -> Result<RequestStatusResponse, LookupError> {
     let path = [
         "request_status".as_bytes(),
         request_id.as_slice(),
@@ -185,38 +206,50 @@ pub(crate) fn lookup_subnet<Storage: AsRef<[u8]> + Clone>(
     } else {
         Principal::self_authenticating(root_key)
     };
-    let subnet_tree = lookup_tree(&certificate.tree, [b"subnet", subnet_id.as_slice()])?;
-    let key = lookup_value(&subnet_tree, [b"public_key".as_ref()])?.to_vec();
+    let subnet_tree =
+        lookup_tree(&certificate.tree, [b"subnet", subnet_id.as_slice()]).context(Protocol)?;
+    let key = lookup_value(&subnet_tree, [b"public_key".as_ref()])
+        .context(Protocol)?
+        .to_vec();
     let canister_ranges: Vec<(Principal, Principal)> =
         if let Some(delegation) = &certificate.delegation {
             let delegation: Certificate<Vec<u8>> =
-                serde_cbor::from_slice(delegation.certificate.as_ref())?;
-            serde_cbor::from_slice(lookup_value(
-                &delegation.tree,
-                [b"subnet", subnet_id.as_slice(), b"canister_ranges"],
-            )?)?
+                serde_cbor::from_slice(delegation.certificate.as_ref()).context(Protocol)?;
+            serde_cbor::from_slice(
+                lookup_value(
+                    &delegation.tree,
+                    [b"subnet", subnet_id.as_slice(), b"canister_ranges"],
+                )
+                .context(Protocol)?,
+            )
+            .context(Protocol)?
         } else {
-            serde_cbor::from_slice(lookup_value(&subnet_tree, [b"canister_ranges".as_ref()])?)?
+            serde_cbor::from_slice(
+                lookup_value(&subnet_tree, [b"canister_ranges".as_ref()]).context(Protocol)?,
+            )
+            .context(Protocol)?
         };
-    let node_keys_subtree = lookup_tree(&subnet_tree, [b"node".as_ref()])?;
+    let node_keys_subtree = lookup_tree(&subnet_tree, [b"node".as_ref()]).context(Protocol)?;
     let mut node_keys = HashMap::new();
     for path in node_keys_subtree.list_paths() {
         if path.len() < 2 {
             // if it's absent, it's because this is the wrong subnet
-            return Err(AgentError::CertificateNotAuthorized());
+            return Err(ErrorCode::CertificateNotAuthorized).context(Trust);
         }
         if path[1].as_bytes() != b"public_key" {
             continue;
         }
         if path.len() > 2 {
-            return Err(AgentError::LookupPathError(
+            return Err(ErrorCode::LookupPathError(
                 path.into_iter()
                     .map(|label| label.as_bytes().to_vec().into())
                     .collect(),
-            ));
+            ))
+            .context(Protocol);
         }
         let node_id = Principal::from_slice(path[0].as_bytes());
-        let node_key = lookup_value(&node_keys_subtree, [node_id.as_slice(), b"public_key"])?;
+        let node_key = lookup_value(&node_keys_subtree, [node_id.as_slice(), b"public_key"])
+            .context(Protocol)?;
         node_keys.insert(node_id, node_key.to_vec());
     }
     let mut range_set = RangeInclusiveSet::new_with_step_fns();
@@ -233,7 +266,7 @@ pub(crate) fn lookup_subnet<Storage: AsRef<[u8]> + Clone>(
 
 pub(crate) fn lookup_api_boundary_nodes<Storage: AsRef<[u8]> + Clone>(
     certificate: Certificate<Storage>,
-) -> Result<Vec<ApiBoundaryNode>, AgentError> {
+) -> Result<Vec<ApiBoundaryNode>, LookupError> {
     // API boundary nodes paths in the state tree, as defined in the spec (https://internetcomputer.org/docs/current/references/ic-interface-spec#state-tree-api-bn).
     let api_bn_path = "api_boundary_nodes".as_bytes();
     let domain_path = "domain".as_bytes();
@@ -249,19 +282,18 @@ pub(crate) fn lookup_api_boundary_nodes<Storage: AsRef<[u8]> + Clone>(
     for node_id in node_ids {
         let domain =
             String::from_utf8(lookup_value(&api_bn_tree, [node_id, domain_path])?.to_vec())
-                .map_err(|err| AgentError::Utf8ReadError(err.utf8_error()))?;
+                .context_deserialize([node_id, domain_path])?;
 
         let ipv6_address =
             String::from_utf8(lookup_value(&api_bn_tree, [node_id, ipv6_path])?.to_vec())
-                .map_err(|err| AgentError::Utf8ReadError(err.utf8_error()))?;
+                .context_deserialize([node_id, ipv6_path])?;
 
         let ipv4_address = match lookup_value(&api_bn_tree, [node_id, ipv4_path]) {
-            Ok(ipv4) => Some(
-                String::from_utf8(ipv4.to_vec())
-                    .map_err(|err| AgentError::Utf8ReadError(err.utf8_error()))?,
-            ),
+            Ok(ipv4) => {
+                Some(String::from_utf8(ipv4.to_vec()).context_deserialize([node_id, ipv4_path])?)
+            }
             // By convention an absent path `/api_boundary_nodes/<node_id>/ipv4_address` in the state tree signifies that ipv4 is None.
-            Err(AgentError::LookupPathAbsent(_)) => None,
+            Err(LookupError::Absent { .. }) => None,
             Err(err) => return Err(err),
         };
 
@@ -289,7 +321,10 @@ pub trait LookupPath {
 
 impl<'b, const N: usize> LookupPath for [&'b [u8]; N] {
     type Item = &'b [u8];
-    type Iter<'a> = std::slice::Iter<'a, &'b [u8]> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, &'b [u8]>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         self.as_slice().iter()
     }
@@ -299,7 +334,10 @@ impl<'b, const N: usize> LookupPath for [&'b [u8]; N] {
 }
 impl<'b, 'c> LookupPath for &'c [&'b [u8]] {
     type Item = &'b [u8];
-    type Iter<'a> = std::slice::Iter<'a, &'b [u8]> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, &'b [u8]>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self)
     }
@@ -309,7 +347,10 @@ impl<'b, 'c> LookupPath for &'c [&'b [u8]] {
 }
 impl<'b> LookupPath for Vec<&'b [u8]> {
     type Item = &'b [u8];
-    type Iter<'a> = std::slice::Iter<'a, &'b [u8]> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, &'b [u8]>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self.as_slice())
     }
@@ -320,7 +361,10 @@ impl<'b> LookupPath for Vec<&'b [u8]> {
 
 impl<const N: usize> LookupPath for [Vec<u8>; N] {
     type Item = Vec<u8>;
-    type Iter<'a> = std::slice::Iter<'a, Vec<u8>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Vec<u8>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         self.as_slice().iter()
     }
@@ -330,7 +374,10 @@ impl<const N: usize> LookupPath for [Vec<u8>; N] {
 }
 impl<'c> LookupPath for &'c [Vec<u8>] {
     type Item = Vec<u8>;
-    type Iter<'a> = std::slice::Iter<'a, Vec<u8>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Vec<u8>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self)
     }
@@ -340,7 +387,10 @@ impl<'c> LookupPath for &'c [Vec<u8>] {
 }
 impl LookupPath for Vec<Vec<u8>> {
     type Item = Vec<u8>;
-    type Iter<'a> = std::slice::Iter<'a, Vec<u8>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Vec<u8>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self.as_slice())
     }
@@ -351,7 +401,10 @@ impl LookupPath for Vec<Vec<u8>> {
 
 impl<Storage: AsRef<[u8]> + Into<Vec<u8>>, const N: usize> LookupPath for [Label<Storage>; N] {
     type Item = Label<Storage>;
-    type Iter<'a> = std::slice::Iter<'a, Label<Storage>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Label<Storage>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         self.as_slice().iter()
     }
@@ -361,7 +414,10 @@ impl<Storage: AsRef<[u8]> + Into<Vec<u8>>, const N: usize> LookupPath for [Label
 }
 impl<'c, Storage: AsRef<[u8]> + Into<Vec<u8>>> LookupPath for &'c [Label<Storage>] {
     type Item = Label<Storage>;
-    type Iter<'a> = std::slice::Iter<'a, Label<Storage>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Label<Storage>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self)
     }
@@ -373,7 +429,10 @@ impl<'c, Storage: AsRef<[u8]> + Into<Vec<u8>>> LookupPath for &'c [Label<Storage
 }
 impl LookupPath for Vec<Label<Vec<u8>>> {
     type Item = Label<Vec<u8>>;
-    type Iter<'a> = std::slice::Iter<'a, Label<Vec<u8>>> where Self: 'a;
+    type Iter<'a>
+        = std::slice::Iter<'a, Label<Vec<u8>>>
+    where
+        Self: 'a;
     fn iter(&self) -> Self::Iter<'_> {
         <[_]>::iter(self.as_slice())
     }
@@ -388,13 +447,18 @@ impl LookupPath for Vec<Label<Vec<u8>>> {
 pub fn lookup_value<P: LookupPath, Storage: AsRef<[u8]>>(
     tree: &HashTree<Storage>,
     path: P,
-) -> Result<&[u8], AgentError> {
-    use AgentError::*;
+) -> Result<&[u8], LookupError> {
     match tree.lookup_path(path.iter()) {
-        LookupResult::Absent => Err(LookupPathAbsent(path.into_vec())),
-        LookupResult::Unknown => Err(LookupPathUnknown(path.into_vec())),
+        LookupResult::Absent => Err(LookupError::Absent {
+            path: path.into_vec(),
+        }),
+        LookupResult::Unknown => Err(LookupError::Unacknowledged {
+            path: path.into_vec(),
+        }),
         LookupResult::Found(value) => Ok(value),
-        LookupResult::Error => Err(LookupPathError(path.into_vec())),
+        LookupResult::Error => Err(LookupError::Malformed {
+            path: path.into_vec(),
+        }),
     }
 }
 
@@ -404,11 +468,83 @@ pub fn lookup_value<P: LookupPath, Storage: AsRef<[u8]>>(
 pub fn lookup_tree<P: LookupPath, Storage: AsRef<[u8]> + Clone>(
     tree: &HashTree<Storage>,
     path: P,
-) -> Result<HashTree<Storage>, AgentError> {
-    use AgentError::*;
+) -> Result<HashTree<Storage>, LookupError> {
     match tree.lookup_subtree(path.iter()) {
-        SubtreeLookupResult::Absent => Err(LookupPathAbsent(path.into_vec())),
-        SubtreeLookupResult::Unknown => Err(LookupPathUnknown(path.into_vec())),
+        SubtreeLookupResult::Absent => Err(LookupError::Absent {
+            path: path.into_vec(),
+        }),
+        SubtreeLookupResult::Unknown => Err(LookupError::Unacknowledged {
+            path: path.into_vec(),
+        }),
         SubtreeLookupResult::Found(value) => Ok(value),
     }
 }
+
+#[derive(Debug)]
+pub enum LookupError {
+    Absent {
+        path: Vec<Label<Vec<u8>>>,
+    },
+    Unacknowledged {
+        path: Vec<Label<Vec<u8>>>,
+    },
+    Malformed {
+        path: Vec<Label<Vec<u8>>>,
+    },
+    Deserialize {
+        path: Vec<Label<Vec<u8>>>,
+        source: Box<dyn Error + Send + Sync>,
+    },
+}
+
+impl Display for LookupError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Absent { path } => write!(f, "path `{}` doesn't exist", path.iter().format("/")),
+            Self::Malformed { path } => {
+                write!(f, "path `{}` was malformed", path.iter().format("/"))
+            }
+            Self::Unacknowledged { path } => {
+                write!(f, "path `{}` wasn't described", path.iter().format("/"))
+            }
+            Self::Deserialize { path, source } => write!(
+                f,
+                "error deserializing at path {}: {source}",
+                path.iter().format("/")
+            ),
+        }
+    }
+}
+
+impl Error for LookupError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::Deserialize { source, .. } => Some(&**source),
+            _ => None,
+        }
+    }
+}
+
+trait LookupResultExt<T> {
+    fn context_deserialize(self, path: impl LookupPath) -> Result<T, LookupError>;
+}
+
+impl<T, E: Error + Send + Sync + 'static> LookupResultExt<T> for Result<T, E> {
+    fn context_deserialize(self, path: impl LookupPath) -> Result<T, LookupError> {
+        self.map_err(|source| LookupError::Deserialize {
+            path: path.into_vec(),
+            source: Box::new(source),
+        })
+    }
+}
+
+#[derive(Debug)]
+struct InvalidRequestStatusError(String);
+
+impl Display for InvalidRequestStatusError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Invalid request status `{}`", self.0)
+    }
+}
+
+impl Error for InvalidRequestStatusError {}
diff --git a/ic-agent/src/agent/route_provider.rs b/ic-agent/src/agent/route_provider.rs
index 37caad2e..71c25060 100644
--- a/ic-agent/src/agent/route_provider.rs
+++ b/ic-agent/src/agent/route_provider.rs
@@ -19,9 +19,9 @@ use std::{
 };
 use url::Url;
 
-use crate::agent::AgentError;
+use crate::agent::agent_error::{AgentError, ErrorKind::*};
 
-use super::HttpService;
+use super::{agent_error::ResultExt, HttpService};
 #[cfg(not(feature = "_internal_dynamic-routing"))]
 pub(crate) mod dynamic_routing;
 #[cfg(feature = "_internal_dynamic-routing")]
@@ -86,7 +86,7 @@ impl RouteProvider for RoundRobinRouteProvider {
     /// Generates a url for the given endpoint.
     fn route(&self) -> Result<Url, AgentError> {
         if self.routes.is_empty() {
-            return Err(AgentError::RouteProviderError(
+            return Err(AgentError::new_route_provider_error_without_context(
                 "No routing urls provided".to_string(),
             ));
         }
@@ -128,21 +128,23 @@ impl RoundRobinRouteProvider {
         let routes: Result<Vec<Url>, _> = routes
             .into_iter()
             .map(|url| {
-                Url::from_str(url.as_ref()).and_then(|mut url| {
-                    // rewrite *.ic0.app to ic0.app
-                    if let Some(domain) = url.domain() {
-                        if domain.ends_with(IC0_SUB_DOMAIN) {
-                            url.set_host(Some(IC0_DOMAIN))?;
-                        } else if domain.ends_with(ICP0_SUB_DOMAIN) {
-                            url.set_host(Some(ICP0_DOMAIN))?;
-                        } else if domain.ends_with(ICP_API_SUB_DOMAIN) {
-                            url.set_host(Some(ICP_API_DOMAIN))?;
-                        } else if domain.ends_with(LOCALHOST_SUB_DOMAIN) {
-                            url.set_host(Some(LOCALHOST_DOMAIN))?;
+                Url::from_str(url.as_ref())
+                    .and_then(|mut url| {
+                        // rewrite *.ic0.app to ic0.app
+                        if let Some(domain) = url.domain() {
+                            if domain.ends_with(IC0_SUB_DOMAIN) {
+                                url.set_host(Some(IC0_DOMAIN))?;
+                            } else if domain.ends_with(ICP0_SUB_DOMAIN) {
+                                url.set_host(Some(ICP0_DOMAIN))?;
+                            } else if domain.ends_with(ICP_API_SUB_DOMAIN) {
+                                url.set_host(Some(ICP_API_DOMAIN))?;
+                            } else if domain.ends_with(LOCALHOST_SUB_DOMAIN) {
+                                url.set_host(Some(LOCALHOST_DOMAIN))?;
+                            }
                         }
-                    }
-                    Ok(url)
-                })
+                        Ok(url)
+                    })
+                    .context(Input)
             })
             .collect();
         Ok(Self {
@@ -178,20 +180,17 @@ impl DynamicRouteProvider {
         strategy: DynamicRoutingStrategy,
     ) -> Result<Self, AgentError> {
         let seed_nodes: Result<Vec<_>, _> = seed_domains.into_iter().map(Node::new).collect();
+        let seed_nodes = seed_nodes.context(Input)?;
         let boxed = match strategy {
             DynamicRoutingStrategy::ByLatency => Box::new(
-                DynamicRouteProviderBuilder::new(
-                    LatencyRoutingSnapshot::new(),
-                    seed_nodes?,
-                    client,
-                )
-                .build()
-                .await,
+                DynamicRouteProviderBuilder::new(LatencyRoutingSnapshot::new(), seed_nodes, client)
+                    .build()
+                    .await,
             ) as Box<dyn RouteProvider>,
             DynamicRoutingStrategy::RoundRobin => Box::new(
                 DynamicRouteProviderBuilder::new(
                     RoundRobinRoutingSnapshot::new(),
-                    seed_nodes?,
+                    seed_nodes,
                     client,
                 )
                 .build()
@@ -209,22 +208,19 @@ impl DynamicRouteProvider {
         health_check_interval: Duration,
     ) -> Result<Self, AgentError> {
         let seed_nodes: Result<Vec<_>, _> = seed_domains.into_iter().map(Node::new).collect();
+        let seed_nodes = seed_nodes.context(Input)?;
         let boxed = match strategy {
             DynamicRoutingStrategy::ByLatency => Box::new(
-                DynamicRouteProviderBuilder::new(
-                    LatencyRoutingSnapshot::new(),
-                    seed_nodes?,
-                    client,
-                )
-                .with_fetch_period(list_update_interval)
-                .with_check_period(health_check_interval)
-                .build()
-                .await,
+                DynamicRouteProviderBuilder::new(LatencyRoutingSnapshot::new(), seed_nodes, client)
+                    .with_fetch_period(list_update_interval)
+                    .with_check_period(health_check_interval)
+                    .build()
+                    .await,
             ) as Box<dyn RouteProvider>,
             DynamicRoutingStrategy::RoundRobin => Box::new(
                 DynamicRouteProviderBuilder::new(
                     RoundRobinRoutingSnapshot::new(),
-                    seed_nodes?,
+                    seed_nodes,
                     client,
                 )
                 .with_fetch_period(list_update_interval)
@@ -316,10 +312,7 @@ mod tests {
         let provider = RoundRobinRouteProvider::new::<&str>(vec![])
             .expect("failed to create a route provider");
         let result = provider.route().unwrap_err();
-        assert_eq!(
-            result,
-            AgentError::RouteProviderError("No routing urls provided".to_string())
-        );
+        assert!(format!("{result}").contains("No routing urls provided"));
     }
 
     #[test]
diff --git a/ic-agent/src/agent/route_provider/dynamic_routing/dynamic_route_provider.rs b/ic-agent/src/agent/route_provider/dynamic_routing/dynamic_route_provider.rs
index 10bef122..5dfb82a2 100644
--- a/ic-agent/src/agent/route_provider/dynamic_routing/dynamic_route_provider.rs
+++ b/ic-agent/src/agent/route_provider/dynamic_routing/dynamic_route_provider.rs
@@ -6,8 +6,8 @@ use std::{
 };
 
 use arc_swap::ArcSwap;
-use candid::Principal;
 use futures_util::FutureExt;
+use ic_principal::Principal;
 use stop_token::StopSource;
 use thiserror::Error;
 use url::Url;
@@ -170,7 +170,9 @@ where
     fn route(&self) -> Result<Url, AgentError> {
         let snapshot = self.routing_snapshot.load();
         let node = snapshot.next_node().ok_or_else(|| {
-            AgentError::RouteProviderError("No healthy API nodes found.".to_string())
+            AgentError::new_route_provider_error_without_context(
+                "No healthy API nodes found.".to_string(),
+            )
         })?;
         Ok(node.to_routing_url())
     }
@@ -179,7 +181,7 @@ where
         let snapshot = self.routing_snapshot.load();
         let nodes = snapshot.next_n_nodes(n);
         if nodes.is_empty() {
-            return Err(AgentError::RouteProviderError(
+            return Err(AgentError::new_route_provider_error_without_context(
                 "No healthy API nodes found.".to_string(),
             ));
         };
@@ -298,7 +300,7 @@ mod tests {
             },
             RouteProvider, RoutesStats,
         },
-        Agent, AgentError,
+        Agent,
     };
 
     static TRACING_INIT: Once = Once::new();
@@ -523,10 +525,7 @@ mod tests {
         for _ in 0..4 {
             tokio::time::sleep(check_interval).await;
             let result = route_provider.route();
-            assert_eq!(
-                result.unwrap_err(),
-                AgentError::RouteProviderError("No healthy API nodes found.".to_string())
-            );
+            assert!(format!("{}", result.unwrap_err()).contains("No healthy API nodes found."));
         }
 
         // Test 2: calls to route() return both seeds, as they become healthy.
@@ -573,10 +572,7 @@ mod tests {
         tokio::time::sleep(2 * check_interval).await;
         for _ in 0..4 {
             let result = route_provider.route();
-            assert_eq!(
-                result.unwrap_err(),
-                AgentError::RouteProviderError("No healthy API nodes found.".to_string())
-            );
+            assert!(format!("{}", result.unwrap_err()).contains("No healthy API nodes found."));
         }
     }
 
@@ -610,10 +606,7 @@ mod tests {
         for _ in 0..4 {
             tokio::time::sleep(check_interval).await;
             let result = route_provider.route();
-            assert_eq!(
-                result.unwrap_err(),
-                AgentError::RouteProviderError("No healthy API nodes found.".to_string())
-            );
+            assert!(format!("{}", result.unwrap_err()).contains("No healthy API nodes found"));
         }
     }
 
diff --git a/ic-agent/src/agent/route_provider/dynamic_routing/nodes_fetch.rs b/ic-agent/src/agent/route_provider/dynamic_routing/nodes_fetch.rs
index 3318f03d..63330564 100644
--- a/ic-agent/src/agent/route_provider/dynamic_routing/nodes_fetch.rs
+++ b/ic-agent/src/agent/route_provider/dynamic_routing/nodes_fetch.rs
@@ -1,6 +1,6 @@
 use async_trait::async_trait;
-use candid::Principal;
 use futures_util::FutureExt;
+use ic_principal::Principal;
 use std::{fmt::Debug, sync::Arc, time::Duration};
 use stop_token::StopToken;
 use url::Url;
diff --git a/ic-agent/src/export.rs b/ic-agent/src/export.rs
index dbdedcf2..ec7b0f18 100644
--- a/ic-agent/src/export.rs
+++ b/ic-agent/src/export.rs
@@ -1,4 +1,4 @@
 //! A module to re-export types that are visible through the ic-agent API.
 #[doc(inline)]
-pub use candid::types::principal::{Principal, PrincipalError};
+pub use ic_principal::{Principal, PrincipalError};
 pub use reqwest;
diff --git a/ic-agent/src/identity/delegated.rs b/ic-agent/src/identity/delegated.rs
index 08b362ec..18209a1f 100644
--- a/ic-agent/src/identity/delegated.rs
+++ b/ic-agent/src/identity/delegated.rs
@@ -1,6 +1,6 @@
-use candid::Principal;
 use der::{Decode, SliceReader};
 use ecdsa::signature::Verifier;
+use ic_principal::Principal;
 use k256::Secp256k1;
 use p256::NistP256;
 use pkcs8::{spki::SubjectPublicKeyInfoRef, AssociatedOid, ObjectIdentifier};
diff --git a/ic-agent/src/lib.rs b/ic-agent/src/lib.rs
index 40254364..bcce7061 100644
--- a/ic-agent/src/lib.rs
+++ b/ic-agent/src/lib.rs
@@ -111,7 +111,7 @@ pub mod agent;
 pub mod export;
 pub mod identity;
 
-use agent::response_authentication::LookupPath;
+use agent::response_authentication::{LookupError, LookupPath};
 #[doc(inline)]
 pub use agent::{agent_error, agent_error::AgentError, Agent, NonceFactory, NonceGenerator};
 #[doc(inline)]
@@ -128,6 +128,6 @@ pub use ic_certification::{hash_tree, Certificate};
 pub fn lookup_value<P: LookupPath, Storage: AsRef<[u8]>>(
     tree: &ic_certification::certificate::Certificate<Storage>,
     path: P,
-) -> Result<&[u8], AgentError> {
+) -> Result<&[u8], LookupError> {
     agent::response_authentication::lookup_value(&tree.tree, path)
 }
diff --git a/ic-agent/src/util.rs b/ic-agent/src/util.rs
index 232b2eca..6fdd1634 100644
--- a/ic-agent/src/util.rs
+++ b/ic-agent/src/util.rs
@@ -1,9 +1,16 @@
 #![allow(dead_code)]
 
+use std::cell::RefCell;
 use std::future::Future;
+use std::mem::swap;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use std::thread::LocalKey;
 use std::time::Duration;
 
-pub async fn sleep(d: Duration) {
+use pin_project::pin_project;
+
+pub(crate) async fn sleep(d: Duration) {
     #[cfg(not(all(target_family = "wasm", feature = "wasm-bindgen")))]
     tokio::time::sleep(d).await;
     #[cfg(all(target_family = "wasm", feature = "wasm-bindgen"))]
@@ -24,15 +31,88 @@ pub async fn sleep(d: Duration) {
 }
 
 #[cfg(all(target_family = "wasm", feature = "wasm-bindgen"))]
-pub fn spawn(f: impl Future<Output = ()> + 'static) {
+pub(crate) fn spawn(f: impl Future<Output = ()> + 'static) {
     wasm_bindgen_futures::spawn_local(f);
 }
 
 #[cfg(not(all(target_family = "wasm", feature = "wasm-bindgen")))]
-pub fn spawn(f: impl Future<Output = ()> + Send + 'static) {
+pub(crate) fn spawn(f: impl Future<Output = ()> + Send + 'static) {
     tokio::spawn(f);
 }
 
 macro_rules! log {
     ($name:ident, $($t:tt)*) => { #[cfg(feature = "tracing")] { tracing::$name!($($t)*) } };
 }
+
+pub(crate) struct TaskLocal<T>(RefCell<Option<T>>);
+
+impl<T> TaskLocal<T> {
+    pub(crate) const fn new() -> Self {
+        Self(RefCell::new(None))
+    }
+}
+
+#[pin_project]
+pub(crate) struct TaskLocalContextFuture<T: 'static, F> {
+    #[pin]
+    f: F,
+    t: Option<T>,
+    key: &'static LocalKey<TaskLocal<T>>,
+}
+
+macro_rules! task_local {
+    ($vis:vis static $name:ident : $type:ty ; ) => {
+        std::thread_local! {
+            $vis static $name : $crate::util::TaskLocal<$type> = $crate::util::TaskLocal::new();
+        }
+    };
+}
+
+pub(crate) fn in_context_of<T: 'static, F: Future>(
+    key: &'static LocalKey<TaskLocal<T>>,
+    val: T,
+    f: F,
+) -> TaskLocalContextFuture<T, F> {
+    TaskLocalContextFuture {
+        t: Some(val),
+        f,
+        key,
+    }
+}
+
+impl<T, F> Future for TaskLocalContextFuture<T, F>
+where
+    F: Future,
+{
+    type Output = F::Output;
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let this = self.project();
+        this.key.with(|key| swap(&mut *key.0.borrow_mut(), this.t));
+        let result = this.f.poll(cx);
+        this.key.with(|key| swap(&mut *key.0.borrow_mut(), this.t));
+        result
+    }
+}
+
+pub(crate) struct NoContextError;
+
+pub(crate) fn try_from_context<T: 'static, R>(
+    key: &'static LocalKey<TaskLocal<T>>,
+    f: impl FnOnce(&mut T) -> R,
+) -> Result<R, NoContextError> {
+    key.with(|key| {
+        let mut borrow = key.0.borrow_mut();
+        if let Some(val) = &mut *borrow {
+            Ok(f(val))
+        } else {
+            Err(NoContextError)
+        }
+    })
+}
+
+pub(crate) fn from_context<T: 'static, R>(
+    key: &'static LocalKey<TaskLocal<T>>,
+    f: impl FnOnce(&mut T) -> R,
+) -> R {
+    try_from_context(key, f).unwrap_or_else(|_| panic!("no context available"))
+}
diff --git a/ic-utils/src/call.rs b/ic-utils/src/call.rs
index e22fa003..c606d0d2 100644
--- a/ic-utils/src/call.rs
+++ b/ic-utils/src/call.rs
@@ -3,9 +3,10 @@ use candid::{decode_args, decode_one, utils::ArgumentDecoder, CandidType};
 use ic_agent::{
     agent::{CallResponse, UpdateBuilder},
     export::Principal,
-    Agent, AgentError,
+    Agent,
 };
 use serde::de::DeserializeOwned;
+use std::error::Error;
 use std::fmt;
 use std::future::{Future, IntoFuture};
 use std::marker::PhantomData;
@@ -17,19 +18,30 @@ pub use expiry::Expiry;
 /// A type that implements synchronous calls (ie. 'query' calls).
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-pub trait SyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
+pub trait SyncCall: CallIntoFuture<Output = Result<Self::Value, Self::Error>> {
     /// The return type of the Candid function being called.
     type Value: for<'de> ArgumentDecoder<'de> + Send;
-    /// Execute the call, return an array of bytes directly from the canister.
+    /// The error type of the operation.
+    type Error: Error;
+    /// Execute the call, returning an array of bytes directly from the canister.
     #[cfg(feature = "raw")]
-    async fn call_raw(self) -> Result<Vec<u8>, AgentError>;
+    async fn call_raw(self) -> Result<Vec<u8>, Self::Error>;
 
-    /// Execute the call, returning either the value returned by the canister, or an
-    /// error returned by the Agent.
-    async fn call(self) -> Result<Self::Value, AgentError>
+    /// Execute the call, returning a decoded response object.
+    async fn call(self) -> Result<Self::Value, Self::Error>
     where
         Self: Sized + Send,
         Self::Value: 'async_trait;
+
+    /// Apply a transformation function to the error after the call fails.
+    fn map_err<'a, E, F>(self, f: F) -> MapErrSyncCaller<'a, Self, E, F>
+    where
+        Self: Sized + Send + 'a,
+        E: CanisterError + 'a,
+        F: FnOnce(Self::Error) -> E + Send + 'a,
+    {
+        MapErrSyncCaller::new(self, f)
+    }
 }
 
 /// A type that implements asynchronous calls (ie. 'update' calls).
@@ -40,9 +52,11 @@ pub trait SyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
 /// call should be returning.
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-pub trait AsyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
+pub trait AsyncCall: CallIntoFuture<Output = Result<Self::Value, Self::Error>> {
     /// The return type of the Candid function being called.
     type Value: for<'de> ArgumentDecoder<'de> + Send;
+    /// The error type of the operation.
+    type Error: CanisterError;
     /// Execute the call, but returns the `RequestId`. Waiting on the request Id must be
     /// managed by the caller using the Agent directly.
     ///
@@ -52,11 +66,11 @@ pub trait AsyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
     /// the result, and try to deserialize it as a [`String`]. This would be caught by
     /// Rust type system, but in this case it will be checked at runtime (as `RequestId`
     /// does not have a type associated with it).
-    async fn call(self) -> Result<CallResponse<Self::Value>, AgentError>;
+    async fn call(self) -> Result<CallResponse<Self::Value>, Self::Error>;
 
     /// Execute the call, and wait for an answer using an exponential-backoff strategy. The return
     /// type is encoded in the trait.
-    async fn call_and_wait(self) -> Result<Self::Value, AgentError>;
+    async fn call_and_wait(self) -> Result<Self::Value, Self::Error>;
 
     /// Apply a transformation function after the call has been successful. The transformation
     /// is applied with the result.
@@ -117,18 +131,21 @@ pub trait AsyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
     fn and_then<'a, Out2, R, AndThen>(
         self,
         and_then: AndThen,
-    ) -> AndThenAsyncCaller<'a, Self::Value, Out2, Self, R, AndThen>
+    ) -> AndThenAsyncCaller<'a, Self::Value, Out2, Self::Error, Self, R, AndThen>
     where
         Self: Sized + Send + 'a,
         Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-        R: Future<Output = Result<Out2, AgentError>> + Send + 'a,
+        R: Future<Output = Result<Out2, Self::Error>> + Send + 'a,
         AndThen: Send + Fn(Self::Value) -> R + 'a,
     {
         AndThenAsyncCaller::new(self, and_then)
     }
 
     /// Apply a transformation function after the call has been successful. Equivalent to `.and_then(|x| async { map(x) })`.
-    fn map<'a, Out, Map>(self, map: Map) -> MappedAsyncCaller<'a, Self::Value, Out, Self, Map>
+    fn map<'a, Out, Map>(
+        self,
+        map: Map,
+    ) -> MappedAsyncCaller<'a, Self::Value, Out, Self::Error, Self, Map>
     where
         Self: Sized + Send + 'a,
         Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
@@ -136,13 +153,22 @@ pub trait AsyncCall: CallIntoFuture<Output = Result<Self::Value, AgentError>> {
     {
         MappedAsyncCaller::new(self, map)
     }
+
+    /// Apply a transformation function to the error after the call fails.
+    fn map_err<'a, E, F>(self, f: F) -> MapErrAsyncCaller<'a, Self, E, F>
+    where
+        Self: Sized + Send + 'a,
+        E: CanisterError + 'a,
+        F: FnOnce(Self::Error) -> E + Send + 'a,
+    {
+        MapErrAsyncCaller::new(self, f)
+    }
 }
 
 #[cfg(target_family = "wasm")]
-pub(crate) type CallFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, AgentError>> + 'a>>;
+pub(crate) type CallFuture<'a, T, E> = Pin<Box<dyn Future<Output = Result<T, E>> + 'a>>;
 #[cfg(not(target_family = "wasm"))]
-pub(crate) type CallFuture<'a, T> =
-    Pin<Box<dyn Future<Output = Result<T, AgentError>> + Send + 'a>>;
+pub(crate) type CallFuture<'a, T, E> = Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>>;
 #[cfg(not(target_family = "wasm"))]
 #[doc(hidden)]
 pub trait CallIntoFuture: IntoFuture<IntoFuture = <Self as CallIntoFuture>::IntoFuture> {
@@ -159,64 +185,72 @@ where
 #[cfg(target_family = "wasm")]
 use IntoFuture as CallIntoFuture;
 
+use crate::error::CanisterError;
+
 /// A synchronous call encapsulation.
 #[derive(Debug)]
-pub struct SyncCaller<'agent, Out>
+pub struct SyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
 {
     pub(crate) agent: &'agent Agent,
     pub(crate) effective_canister_id: Principal,
     pub(crate) canister_id: Principal,
     pub(crate) method_name: String,
-    pub(crate) arg: Result<Vec<u8>, AgentError>,
+    pub(crate) arg: Result<Vec<u8>, candid::Error>,
     pub(crate) expiry: Expiry,
-    pub(crate) phantom_out: PhantomData<Out>,
+    pub(crate) phantom_out: PhantomData<Result<Out, Err>>,
 }
 
-impl<'agent, Out> SyncCaller<'agent, Out>
+impl<'agent, Out, Err> SyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
 {
     /// Perform the call, consuming the the abstraction. This is a private method.
-    async fn call_raw(self) -> Result<Vec<u8>, AgentError> {
+    async fn call_raw(self) -> Result<Vec<u8>, Err> {
         let mut builder = self.agent.query(&self.canister_id, &self.method_name);
         builder = self.expiry.apply_to_query(builder);
         builder
-            .with_arg(self.arg?)
+            .with_arg(self.arg.map_err(Err::from_candid)?)
             .with_effective_canister_id(self.effective_canister_id)
             .call()
             .await
+            .map_err(Err::from_agent)
     }
 }
 
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-impl<'agent, Out> SyncCall for SyncCaller<'agent, Out>
+impl<'agent, Out, Err> SyncCall for SyncCaller<'agent, Out, Err>
 where
     Self: Sized,
     Out: 'agent + for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
 {
     type Value = Out;
+    type Error = Err;
     #[cfg(feature = "raw")]
-    async fn call_raw(self) -> Result<Vec<u8>, AgentError> {
+    async fn call_raw(self) -> Result<Vec<u8>, Err> {
         Ok(self.call_raw().await?)
     }
 
-    async fn call(self) -> Result<Out, AgentError> {
+    async fn call(self) -> Result<Out, Err> {
         let result = self.call_raw().await?;
 
-        decode_args(&result).map_err(|e| AgentError::CandidError(Box::new(e)))
+        decode_args(&result).map_err(|e| Err::from_candid(e))
     }
 }
 
-impl<'agent, Out> IntoFuture for SyncCaller<'agent, Out>
+impl<'agent, Out, Err> IntoFuture for SyncCaller<'agent, Out, Err>
 where
     Self: Sized,
     Out: 'agent + for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
 {
-    type IntoFuture = CallFuture<'agent, Out>;
-    type Output = Result<Out, AgentError>;
+    type IntoFuture = CallFuture<'agent, Out, Err>;
+    type Output = Result<Out, Err>;
     fn into_future(self) -> Self::IntoFuture {
         SyncCall::call(self)
     }
@@ -224,68 +258,71 @@ where
 
 /// An async caller, encapsulating a call to an update method.
 #[derive(Debug)]
-pub struct AsyncCaller<'agent, Out>
+pub struct AsyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
 {
     pub(crate) agent: &'agent Agent,
     pub(crate) effective_canister_id: Principal,
     pub(crate) canister_id: Principal,
     pub(crate) method_name: String,
-    pub(crate) arg: Result<Vec<u8>, AgentError>,
+    pub(crate) arg: Result<Vec<u8>, candid::Error>,
     pub(crate) expiry: Expiry,
-    pub(crate) phantom_out: PhantomData<Out>,
+    pub(crate) phantom_out: PhantomData<Result<Out, Err>>,
 }
 
-impl<'agent, Out> AsyncCaller<'agent, Out>
+impl<'agent, Out, Err> AsyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'agent,
+    Err: CanisterError,
 {
     /// Build an `UpdateBuilder` call that can be used directly with the [Agent]. This is
     /// essentially downleveling this type into the lower level [ic-agent] abstraction.
-    pub fn build_call(self) -> Result<UpdateBuilder<'agent>, AgentError> {
+    pub fn build_call(self) -> Result<UpdateBuilder<'agent>, Err> {
         let mut builder = self.agent.update(&self.canister_id, &self.method_name);
         builder = self.expiry.apply_to_update(builder);
         builder = builder
-            .with_arg(self.arg?)
+            .with_arg(self.arg.map_err(Err::from_candid)?)
             .with_effective_canister_id(self.effective_canister_id);
         Ok(builder)
     }
 
     /// See [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<Out>, AgentError> {
-        let response_bytes = match self.build_call()?.call().await? {
+    pub async fn call(self) -> Result<CallResponse<Out>, Err> {
+        let response_bytes = match self.build_call()?.call().await.map_err(Err::from_agent)? {
             CallResponse::Response((response_bytes, _)) => response_bytes,
             CallResponse::Poll(request_id) => return Ok(CallResponse::Poll(request_id)),
         };
 
-        let decoded_response =
-            decode_args(&response_bytes).map_err(|e| AgentError::CandidError(Box::new(e)))?;
+        let decoded_response = decode_args(&response_bytes).map_err(Err::from_candid)?;
 
         Ok(CallResponse::Response(decoded_response))
     }
 
     /// See [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<Out, AgentError> {
+    pub async fn call_and_wait(self) -> Result<Out, Err> {
         self.build_call()?
             .call_and_wait()
             .await
-            .and_then(|r| decode_args(&r).map_err(|e| AgentError::CandidError(Box::new(e))))
+            .map_err(Err::from_agent)
+            .and_then(|r| decode_args(&r).map_err(Err::from_candid))
     }
 
     /// Equivalent to calling [`AsyncCall::call_and_wait`] with the expected return type `(T,)`.
-    pub async fn call_and_wait_one<T>(self) -> Result<T, AgentError>
+    pub async fn call_and_wait_one<T>(self) -> Result<T, Err>
     where
         T: DeserializeOwned + CandidType,
     {
         self.build_call()?
             .call_and_wait()
             .await
-            .and_then(|r| decode_one(&r).map_err(|e| AgentError::CandidError(Box::new(e))))
+            .map_err(Err::from_agent)
+            .and_then(|r| decode_one(&r).map_err(Err::from_candid))
     }
 
     /// See [`AsyncCall::map`].
-    pub fn map<Out2, Map>(self, map: Map) -> MappedAsyncCaller<'agent, Out, Out2, Self, Map>
+    pub fn map<Out2, Map>(self, map: Map) -> MappedAsyncCaller<'agent, Out, Out2, Err, Self, Map>
     where
         Out2: for<'de> ArgumentDecoder<'de> + Send,
         Map: Send + Fn(Out) -> Out2,
@@ -296,25 +333,28 @@ where
 
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-impl<'agent, Out> AsyncCall for AsyncCaller<'agent, Out>
+impl<'agent, Out, Err> AsyncCall for AsyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'agent,
+    Err: CanisterError,
 {
     type Value = Out;
-    async fn call(self) -> Result<CallResponse<Out>, AgentError> {
+    type Error = Err;
+    async fn call(self) -> Result<CallResponse<Out>, Err> {
         self.call().await
     }
-    async fn call_and_wait(self) -> Result<Out, AgentError> {
+    async fn call_and_wait(self) -> Result<Out, Err> {
         self.call_and_wait().await
     }
 }
 
-impl<'agent, Out> IntoFuture for AsyncCaller<'agent, Out>
+impl<'agent, Out, Err> IntoFuture for AsyncCaller<'agent, Out, Err>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'agent,
+    Err: CanisterError,
 {
-    type IntoFuture = CallFuture<'agent, Out>;
-    type Output = Result<Out, AgentError>;
+    type IntoFuture = CallFuture<'agent, Out, Err>;
+    type Output = Result<Out, Err>;
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
     }
@@ -327,29 +367,31 @@ pub struct AndThenAsyncCaller<
     'a,
     Out: for<'de> ArgumentDecoder<'de> + Send,
     Out2: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
     Inner: AsyncCall<Value = Out> + Send + 'a,
-    R: Future<Output = Result<Out2, AgentError>> + Send,
+    R: Future<Output = Result<Out2, Err>> + Send,
     AndThen: Send + Fn(Out) -> R,
 > {
     inner: Inner,
     and_then: AndThen,
-    _out: PhantomData<Out>,
-    _out2: PhantomData<Out2>,
+    _out: PhantomData<Result<Out, Err>>,
+    _out2: PhantomData<Result<Out2, Err>>,
     _lifetime: PhantomData<&'a ()>,
 }
 
-impl<'a, Out, Out2, Inner, R, AndThen> fmt::Debug
-    for AndThenAsyncCaller<'a, Out, Out2, Inner, R, AndThen>
+impl<'a, Out, Out2, Err, Inner, R, AndThen> fmt::Debug
+    for AndThenAsyncCaller<'a, Out, Out2, Err, Inner, R, AndThen>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
     Out2: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
     Inner: AsyncCall<Value = Out> + Send + fmt::Debug + 'a,
-    R: Future<Output = Result<Out2, AgentError>> + Send,
+    R: Future<Output = Result<Out2, Err>> + Send,
     AndThen: Send + Fn(Out) -> R + fmt::Debug,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("AndThenAsyncCaller")
-            .field("inner", &self.inner)
+            .field("inner", &self.inner as &dyn fmt::Debug)
             .field("and_then", &self.and_then)
             .field("_out", &self._out)
             .field("_out2", &self._out2)
@@ -357,12 +399,14 @@ where
     }
 }
 
-impl<'a, Out, Out2, Inner, R, AndThen> AndThenAsyncCaller<'a, Out, Out2, Inner, R, AndThen>
+impl<'a, Out, Out2, Err, Inner, R, AndThen>
+    AndThenAsyncCaller<'a, Out, Out2, Err, Inner, R, AndThen>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
     Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
-    R: Future<Output = Result<Out2, AgentError>> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
+    R: Future<Output = Result<Out2, Err>> + Send + 'a,
     AndThen: Send + Fn(Out) -> R + 'a,
 {
     /// Equivalent to `inner.and_then(and_then)`.
@@ -377,7 +421,7 @@ where
     }
 
     /// See [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<Out2>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<Out2>, Err> {
         let raw_response = self.inner.call().await?;
 
         let response = match raw_response {
@@ -391,7 +435,7 @@ where
         Ok(response)
     }
     /// See [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<Out2, AgentError> {
+    pub async fn call_and_wait(self) -> Result<Out2, Err> {
         let v = self.inner.call_and_wait().await?;
 
         let f = (self.and_then)(v);
@@ -403,17 +447,17 @@ where
     pub fn and_then<Out3, R2, AndThen2>(
         self,
         and_then: AndThen2,
-    ) -> AndThenAsyncCaller<'a, Out2, Out3, Self, R2, AndThen2>
+    ) -> AndThenAsyncCaller<'a, Out2, Out3, Err, Self, R2, AndThen2>
     where
         Out3: for<'de> ArgumentDecoder<'de> + Send + 'a,
-        R2: Future<Output = Result<Out3, AgentError>> + Send + 'a,
+        R2: Future<Output = Result<Out3, Err>> + Send + 'a,
         AndThen2: Send + Fn(Out2) -> R2 + 'a,
     {
         AndThenAsyncCaller::new(self, and_then)
     }
 
     /// See [`AsyncCall::map`].
-    pub fn map<Out3, Map>(self, map: Map) -> MappedAsyncCaller<'a, Out2, Out3, Self, Map>
+    pub fn map<Out3, Map>(self, map: Map) -> MappedAsyncCaller<'a, Out2, Out3, Err, Self, Map>
     where
         Out3: for<'de> ArgumentDecoder<'de> + Send,
         Map: Send + Fn(Out2) -> Out3,
@@ -424,37 +468,40 @@ where
 
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-impl<'a, Out, Out2, Inner, R, AndThen> AsyncCall
-    for AndThenAsyncCaller<'a, Out, Out2, Inner, R, AndThen>
+impl<'a, Out, Out2, Err, Inner, R, AndThen> AsyncCall
+    for AndThenAsyncCaller<'a, Out, Out2, Err, Inner, R, AndThen>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
     Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
-    R: Future<Output = Result<Out2, AgentError>> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
+    R: Future<Output = Result<Out2, Err>> + Send + 'a,
     AndThen: Send + Fn(Out) -> R + 'a,
 {
     type Value = Out2;
+    type Error = Err;
 
-    async fn call(self) -> Result<CallResponse<Out2>, AgentError> {
+    async fn call(self) -> Result<CallResponse<Out2>, Err> {
         self.call().await
     }
 
-    async fn call_and_wait(self) -> Result<Out2, AgentError> {
+    async fn call_and_wait(self) -> Result<Out2, Err> {
         self.call_and_wait().await
     }
 }
 
-impl<'a, Out, Out2, Inner, R, AndThen> IntoFuture
-    for AndThenAsyncCaller<'a, Out, Out2, Inner, R, AndThen>
+impl<'a, Out, Out2, Err, Inner, R, AndThen> IntoFuture
+    for AndThenAsyncCaller<'a, Out, Out2, Err, Inner, R, AndThen>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
     Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
-    R: Future<Output = Result<Out2, AgentError>> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
+    R: Future<Output = Result<Out2, Err>> + Send + 'a,
     AndThen: Send + Fn(Out) -> R + 'a,
 {
-    type IntoFuture = CallFuture<'a, Out2>;
-    type Output = Result<Out2, AgentError>;
+    type IntoFuture = CallFuture<'a, Out2, Err>;
+    type Output = Result<Out2, Err>;
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
     }
@@ -466,26 +513,29 @@ pub struct MappedAsyncCaller<
     'a,
     Out: for<'de> ArgumentDecoder<'de> + Send,
     Out2: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
     Inner: AsyncCall<Value = Out> + Send + 'a,
     Map: Send + Fn(Out) -> Out2,
 > {
     inner: Inner,
     map: Map,
-    _out: PhantomData<Out>,
-    _out2: PhantomData<Out2>,
+    _out: PhantomData<Result<Out, Err>>,
+    _out2: PhantomData<Result<Out2, Err>>,
     _lifetime: PhantomData<&'a ()>,
 }
 
-impl<'a, Out, Out2, Inner, Map> fmt::Debug for MappedAsyncCaller<'a, Out, Out2, Inner, Map>
+impl<'a, Out, Out2, Err, Inner, Map> fmt::Debug
+    for MappedAsyncCaller<'a, Out, Out2, Err, Inner, Map>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
     Out2: for<'de> ArgumentDecoder<'de> + Send,
+    Err: CanisterError,
     Inner: AsyncCall<Value = Out> + Send + fmt::Debug + 'a,
     Map: Send + Fn(Out) -> Out2 + fmt::Debug,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("MappedAsyncCaller")
-            .field("inner", &self.inner)
+            .field("inner", &self.inner as &dyn fmt::Debug)
             .field("map", &self.map)
             .field("_out", &self._out)
             .field("_out2", &self._out2)
@@ -493,11 +543,12 @@ where
     }
 }
 
-impl<'a, Out, Out2, Inner, Map> MappedAsyncCaller<'a, Out, Out2, Inner, Map>
+impl<'a, Out, Out2, Err, Inner, Map> MappedAsyncCaller<'a, Out, Out2, Err, Inner, Map>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send,
     Out2: for<'de> ArgumentDecoder<'de> + Send,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
     Map: Send + Fn(Out) -> Out2,
 {
     /// Equivalent to `inner.map(map)`.
@@ -512,7 +563,7 @@ where
     }
 
     /// See [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<Out2>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<Out2>, Err> {
         self.inner.call().await.map(|response| match response {
             CallResponse::Response(response_bytes) => {
                 let mapped_response = (self.map)(response_bytes);
@@ -523,7 +574,7 @@ where
     }
 
     /// See [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<Out2, AgentError> {
+    pub async fn call_and_wait(self) -> Result<Out2, Err> {
         let v = self.inner.call_and_wait().await?;
         Ok((self.map)(v))
     }
@@ -532,17 +583,17 @@ where
     pub fn and_then<Out3, R2, AndThen2>(
         self,
         and_then: AndThen2,
-    ) -> AndThenAsyncCaller<'a, Out2, Out3, Self, R2, AndThen2>
+    ) -> AndThenAsyncCaller<'a, Out2, Out3, Err, Self, R2, AndThen2>
     where
         Out3: for<'de> ArgumentDecoder<'de> + Send + 'a,
-        R2: Future<Output = Result<Out3, AgentError>> + Send + 'a,
+        R2: Future<Output = Result<Out3, Err>> + Send + 'a,
         AndThen2: Send + Fn(Out2) -> R2 + 'a,
     {
         AndThenAsyncCaller::new(self, and_then)
     }
 
     /// See [`AsyncCall::map`].
-    pub fn map<Out3, Map2>(self, map: Map2) -> MappedAsyncCaller<'a, Out2, Out3, Self, Map2>
+    pub fn map<Out3, Map2>(self, map: Map2) -> MappedAsyncCaller<'a, Out2, Out3, Err, Self, Map2>
     where
         Out3: for<'de> ArgumentDecoder<'de> + Send,
         Map2: Send + Fn(Out2) -> Out3,
@@ -553,35 +604,159 @@ where
 
 #[cfg_attr(target_family = "wasm", async_trait(?Send))]
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
-impl<'a, Out, Out2, Inner, Map> AsyncCall for MappedAsyncCaller<'a, Out, Out2, Inner, Map>
+impl<'a, Out, Out2, Err, Inner, Map> AsyncCall for MappedAsyncCaller<'a, Out, Out2, Err, Inner, Map>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
     Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
     Map: Send + Fn(Out) -> Out2 + 'a,
 {
     type Value = Out2;
+    type Error = Err;
 
-    async fn call(self) -> Result<CallResponse<Out2>, AgentError> {
+    async fn call(self) -> Result<CallResponse<Out2>, Err> {
         self.call().await
     }
 
-    async fn call_and_wait(self) -> Result<Out2, AgentError> {
+    async fn call_and_wait(self) -> Result<Out2, Err> {
         self.call_and_wait().await
     }
 }
 
-impl<'a, Out, Out2, Inner, Map> IntoFuture for MappedAsyncCaller<'a, Out, Out2, Inner, Map>
+impl<'a, Out, Out2, Err, Inner, Map> IntoFuture
+    for MappedAsyncCaller<'a, Out, Out2, Err, Inner, Map>
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + 'a,
     Out2: for<'de> ArgumentDecoder<'de> + Send + 'a,
-    Inner: AsyncCall<Value = Out> + Send + 'a,
+    Err: CanisterError,
+    Inner: AsyncCall<Value = Out, Error = Err> + Send + 'a,
     Map: Send + Fn(Out) -> Out2 + 'a,
 {
-    type IntoFuture = CallFuture<'a, Out2>;
-    type Output = Result<Out2, AgentError>;
+    type IntoFuture = CallFuture<'a, Out2, Err>;
+    type Output = Result<Out2, Err>;
 
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
     }
 }
+
+/// A [`SyncCall`] with a transformed error type.
+#[derive(Debug)]
+pub struct MapErrSyncCaller<'a, Inner, Err, Func>
+where
+    Inner: SyncCall + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    inner: Inner,
+    func: Func,
+    lifetime: PhantomData<&'a ()>,
+}
+
+impl<'a, Inner, Err, Func> MapErrSyncCaller<'a, Inner, Err, Func>
+where
+    Inner: SyncCall + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    fn new(inner: Inner, func: Func) -> Self {
+        Self {
+            inner,
+            func,
+            lifetime: PhantomData,
+        }
+    }
+}
+
+#[cfg_attr(target_family = "wasm", async_trait(?Send))]
+#[cfg_attr(not(target_family = "wasm"), async_trait)]
+impl<'a, Inner, Err, Func> SyncCall for MapErrSyncCaller<'a, Inner, Err, Func>
+where
+    Inner: SyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    type Value = Inner::Value;
+    type Error = Err;
+    async fn call(self) -> Result<Inner::Value, Err> {
+        self.inner.call().await.map_err(self.func)
+    }
+
+    #[cfg(feature = "raw")]
+    async fn call_raw(self) -> Result<Vec<u8>, Err> {
+        self.inner.call_raw().await.map_err(self.func)
+    }
+}
+
+impl<'a, Inner, Err, Func> IntoFuture for MapErrSyncCaller<'a, Inner, Err, Func>
+where
+    Inner: SyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    type IntoFuture = CallFuture<'a, Inner::Value, Err>;
+    type Output = Result<Inner::Value, Err>;
+    fn into_future(self) -> Self::IntoFuture {
+        self.call()
+    }
+}
+
+/// An [`AsyncCall`] with a transformed error type.
+#[derive(Debug)]
+pub struct MapErrAsyncCaller<'a, Inner, Err, Func>
+where
+    Inner: AsyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    inner: Inner,
+    func: Func,
+    lifetime: PhantomData<&'a ()>,
+}
+
+impl<'a, Inner, Err, Func> MapErrAsyncCaller<'a, Inner, Err, Func>
+where
+    Inner: AsyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    fn new(inner: Inner, func: Func) -> Self {
+        Self {
+            inner,
+            func,
+            lifetime: PhantomData,
+        }
+    }
+}
+#[cfg_attr(target_family = "wasm", async_trait(?Send))]
+#[cfg_attr(not(target_family = "wasm"), async_trait)]
+impl<'a, Inner, Err, Func> AsyncCall for MapErrAsyncCaller<'a, Inner, Err, Func>
+where
+    Inner: AsyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    type Value = Inner::Value;
+    type Error = Err;
+    async fn call(self) -> Result<CallResponse<Inner::Value>, Err> {
+        self.inner.call().await.map_err(self.func)
+    }
+
+    async fn call_and_wait(self) -> Result<Inner::Value, Err> {
+        self.inner.call_and_wait().await.map_err(self.func)
+    }
+}
+
+impl<'a, Inner, Err, Func> IntoFuture for MapErrAsyncCaller<'a, Inner, Err, Func>
+where
+    Inner: AsyncCall + Send + 'a,
+    Err: CanisterError + 'a,
+    Func: FnOnce(Inner::Error) -> Err + Send + 'a,
+{
+    type Output = Result<Inner::Value, Err>;
+    type IntoFuture = CallFuture<'a, Inner::Value, Err>;
+    fn into_future(self) -> Self::IntoFuture {
+        self.call_and_wait()
+    }
+}
diff --git a/ic-utils/src/canister.rs b/ic-utils/src/canister.rs
index e4f8bfd6..e8532fef 100644
--- a/ic-utils/src/canister.rs
+++ b/ic-utils/src/canister.rs
@@ -1,8 +1,10 @@
 use crate::call::{AsyncCaller, SyncCaller};
+use crate::error::{BaseError, CanisterError};
 use candid::utils::ArgumentEncoder;
 use candid::{ser::IDLBuilder, types::value::IDLValue, utils::ArgumentDecoder, CandidType, Encode};
-use ic_agent::{export::Principal, Agent, AgentError, RequestId};
+use ic_agent::{export::Principal, Agent, RequestId};
 use std::convert::TryInto;
+use std::marker::PhantomData;
 use thiserror::Error;
 
 /// An error happened while building a canister.
@@ -88,6 +90,7 @@ pub struct Canister<'agent> {
 impl<'agent> Canister<'agent> {
     /// Get the canister ID of this canister.
     /// Prefer using [`canister_id`](Canister::canister_id) instead.
+    #[deprecated = "use canister_id"]
     pub fn canister_id_(&self) -> &Principal {
         &self.canister_id
     }
@@ -97,12 +100,12 @@ impl<'agent> Canister<'agent> {
         &self.canister_id
     }
 
-    /// Create an `AsyncCallBuilder` to do an update call.
-    /// Prefer using [`update`](Canister::update) instead.
-    pub fn update_<'canister>(
+    /// Create an `AsyncCallBuilder` to do an update call, auto-selecting the error type.
+    /// Prefer [`update`](Canister::update) for normal use.
+    pub fn update_<'canister, E: CanisterError>(
         &'canister self,
         method_name: &str,
-    ) -> AsyncCallBuilder<'agent, 'canister> {
+    ) -> AsyncCallBuilder<'agent, 'canister, E> {
         AsyncCallBuilder::new(self, method_name)
     }
 
@@ -114,12 +117,12 @@ impl<'agent> Canister<'agent> {
         AsyncCallBuilder::new(self, method_name)
     }
 
-    /// Create a `SyncCallBuilder` to do a query call.
-    /// Prefer using [`query`](Canister::query) instead.
-    pub fn query_<'canister>(
+    /// Create a `SyncCallBuilder` to do a query call, auto-selecting the error type.
+    /// Prefer [`query`](Canister::query) for normal use.
+    pub fn query_<'canister, E: CanisterError>(
         &'canister self,
         method_name: &str,
-    ) -> SyncCallBuilder<'agent, 'canister> {
+    ) -> SyncCallBuilder<'agent, 'canister, E> {
         SyncCallBuilder::new(self, method_name)
     }
 
@@ -135,15 +138,17 @@ impl<'agent> Canister<'agent> {
     pub async fn wait<'canister>(
         &'canister self,
         request_id: &RequestId,
-    ) -> Result<Vec<u8>, AgentError> {
-        self.agent
+    ) -> Result<Vec<u8>, BaseError> {
+        Ok(self
+            .agent
             .wait(request_id, self.canister_id)
             .await
-            .map(|x| x.0)
+            .map(|x| x.0)?)
     }
 
     /// Creates a copy of this canister, changing the canister ID to the provided principal.
     /// Prefer using [`clone_with`](Canister::clone_with) instead.
+    #[deprecated = "use clone_with"]
     pub fn clone_with_(&self, id: Principal) -> Self {
         Self {
             agent: self.agent,
@@ -166,13 +171,13 @@ impl<'agent> Canister<'agent> {
 
 /// A buffer to hold canister argument blob.
 #[derive(Debug, Default)]
-pub struct Argument(pub(crate) Option<Result<Vec<u8>, AgentError>>);
+pub struct Argument(pub(crate) Option<Result<Vec<u8>, candid::Error>>);
 
 impl Argument {
     /// Set an IDL Argument. Can only be called at most once.
     pub fn set_idl_arg<A: CandidType>(&mut self, arg: A) {
         match self.0 {
-            None => self.0 = Some(Encode!(&arg).map_err(|e| e.into())),
+            None => self.0 = Some(Encode!(&arg)),
             Some(_) => panic!("argument is being set more than once"),
         }
     }
@@ -184,8 +189,7 @@ impl Argument {
                 let mut builder = IDLBuilder::new();
                 let result = builder
                     .value_arg(&arg)
-                    .and_then(|builder| builder.serialize_to_vec())
-                    .map_err(Into::into);
+                    .and_then(|builder| builder.serialize_to_vec());
                 self.0 = Some(result);
             }
             Some(_) => panic!("argument is being set more than once"),
@@ -201,7 +205,7 @@ impl Argument {
     }
 
     /// Return the argument blob.
-    pub fn serialize(self) -> Result<Vec<u8>, AgentError> {
+    pub fn serialize(self) -> Result<Vec<u8>, candid::Error> {
         self.0.unwrap_or_else(|| Ok(Encode!()?))
     }
 
@@ -225,8 +229,7 @@ impl Argument {
         let mut builder = IDLBuilder::new();
         let result = tuple
             .encode(&mut builder)
-            .and_then(|_| builder.serialize_to_vec())
-            .map_err(Into::into);
+            .and_then(|_| builder.serialize_to_vec());
         Self(Some(result))
     }
 }
@@ -235,14 +238,15 @@ impl Argument {
 ///
 /// See [`SyncCaller`] for a description of this structure once built.
 #[derive(Debug)]
-pub struct SyncCallBuilder<'agent, 'canister> {
+pub struct SyncCallBuilder<'agent, 'canister, Err = BaseError> {
     canister: &'canister Canister<'agent>,
     method_name: String,
     effective_canister_id: Principal,
     arg: Argument,
+    err: PhantomData<Err>,
 }
 
-impl<'agent: 'canister, 'canister> SyncCallBuilder<'agent, 'canister> {
+impl<'agent: 'canister, 'canister, Err: CanisterError> SyncCallBuilder<'agent, 'canister, Err> {
     /// Create a new instance of an `AsyncCallBuilder`.
     pub(super) fn new<M: Into<String>>(
         canister: &'canister Canister<'agent>,
@@ -253,11 +257,12 @@ impl<'agent: 'canister, 'canister> SyncCallBuilder<'agent, 'canister> {
             method_name: method_name.into(),
             effective_canister_id: canister.canister_id().to_owned(),
             arg: Default::default(),
+            err: PhantomData,
         }
     }
 }
 
-impl<'agent: 'canister, 'canister> SyncCallBuilder<'agent, 'canister> {
+impl<'agent: 'canister, 'canister, Err: CanisterError> SyncCallBuilder<'agent, 'canister, Err> {
     /// Set the argument with candid argument. Can be called at most once.
     pub fn with_arg<Argument>(mut self, arg: Argument) -> Self
     where
@@ -294,7 +299,7 @@ impl<'agent: 'canister, 'canister> SyncCallBuilder<'agent, 'canister> {
     }
 
     /// Builds a [`SyncCaller`] from this builder's state.
-    pub fn build<Output>(self) -> SyncCaller<'agent, Output>
+    pub fn build<Output>(self) -> SyncCaller<'agent, Output, Err>
     where
         Output: for<'de> ArgumentDecoder<'de> + Send + Sync,
     {
@@ -315,29 +320,28 @@ impl<'agent: 'canister, 'canister> SyncCallBuilder<'agent, 'canister> {
 ///
 /// See [`AsyncCaller`] for a description of this structure.
 #[derive(Debug)]
-pub struct AsyncCallBuilder<'agent, 'canister> {
+pub struct AsyncCallBuilder<'agent, 'canister, Err = BaseError> {
     canister: &'canister Canister<'agent>,
     method_name: String,
     effective_canister_id: Principal,
     arg: Argument,
+    err: PhantomData<Err>,
 }
 
-impl<'agent: 'canister, 'canister> AsyncCallBuilder<'agent, 'canister> {
+impl<'agent: 'canister, 'canister, Err: CanisterError> AsyncCallBuilder<'agent, 'canister, Err> {
     /// Create a new instance of an `AsyncCallBuilder`.
-    pub(super) fn new(
-        canister: &'canister Canister<'agent>,
-        method_name: &str,
-    ) -> AsyncCallBuilder<'agent, 'canister> {
+    pub(super) fn new(canister: &'canister Canister<'agent>, method_name: &str) -> Self {
         Self {
             canister,
             method_name: method_name.to_string(),
             effective_canister_id: canister.canister_id().to_owned(),
             arg: Default::default(),
+            err: PhantomData,
         }
     }
 }
 
-impl<'agent: 'canister, 'canister> AsyncCallBuilder<'agent, 'canister> {
+impl<'agent: 'canister, 'canister, Err: CanisterError> AsyncCallBuilder<'agent, 'canister, Err> {
     /// Set the argument with Candid argument. Can be called at most once.
     pub fn with_arg<Argument>(mut self, arg: Argument) -> Self
     where
@@ -366,7 +370,7 @@ impl<'agent: 'canister, 'canister> AsyncCallBuilder<'agent, 'canister> {
     }
 
     /// Builds an [`AsyncCaller`] from this builder's state.
-    pub fn build<Output>(self) -> AsyncCaller<'agent, Output>
+    pub fn build<Output>(self) -> AsyncCaller<'agent, Output, Err>
     where
         Output: for<'de> ArgumentDecoder<'de> + Send + Sync,
     {
diff --git a/ic-utils/src/error.rs b/ic-utils/src/error.rs
new file mode 100644
index 00000000..17a5ac9f
--- /dev/null
+++ b/ic-utils/src/error.rs
@@ -0,0 +1,56 @@
+use ic_agent::AgentError;
+use thiserror::Error;
+
+/// A canister error for canisters that don't have any custom error cases.
+#[derive(Debug, Error)]
+pub enum BaseError {
+    /// Agent error.
+    #[error("agent error: {0}")]
+    Agent(#[from] AgentError),
+    /// Candid error.
+    #[error("{0}")]
+    Candid(#[from] candid::Error),
+}
+
+/// Trait implemented by canister errors.
+pub trait CanisterError: std::error::Error + Send + Sync + 'static {
+    /// Creates an error from a context-free Candid error.
+    fn from_candid(err: candid::Error) -> Self;
+    /// Creates an error from a context-free agent error.
+    fn from_agent(err: AgentError) -> Self;
+    /// If this error wraps an agent error, returns it.
+    fn as_agent(&self) -> Option<&AgentError>;
+}
+
+macro_rules! impl_canister_error {
+    (@ $name:path) => {
+        impl $crate::error::CanisterError for $name {
+            fn from_agent(err: ic_agent::AgentError) -> Self {
+                Self::from(err)
+            }
+            fn from_candid(err: candid::Error) -> Self {
+                Self::from(err)
+            }
+            fn as_agent(&self) -> Option<&ic_agent::AgentError> {
+                match self {
+                    Self::Agent(err) => Some(err),
+                    _ => None,
+                }
+            }
+        }
+    };
+    ($name:path) => {
+        impl From<$crate::error::BaseError> for $name {
+            fn from(base: BaseError) -> Self {
+                match base {
+                    BaseError::Agent(a) => Self::Agent(a),
+                    BaseError::Candid(c) => Self::Candid(c),
+                }
+            }
+        }
+        $crate::error::impl_canister_error!(@ $name);
+    };
+}
+pub(crate) use impl_canister_error;
+
+impl_canister_error!(@ BaseError);
diff --git a/ic-utils/src/interfaces/bitcoin_canister.rs b/ic-utils/src/interfaces/bitcoin_canister.rs
index f34ca52e..0c3e370d 100644
--- a/ic-utils/src/interfaces/bitcoin_canister.rs
+++ b/ic-utils/src/interfaces/bitcoin_canister.rs
@@ -3,11 +3,13 @@
 use std::ops::Deref;
 
 use candid::{CandidType, Principal};
-use ic_agent::{Agent, AgentError};
+use ic_agent::Agent;
 use serde::Deserialize;
+use thiserror::Error;
 
 use crate::{
     call::{AsyncCall, SyncCall},
+    error::BaseError,
     Canister,
 };
 
@@ -18,6 +20,12 @@ pub struct BitcoinCanister<'agent> {
     network: BitcoinNetwork,
 }
 
+/// An error that can occur when constructing a Bitcoin canister.
+#[derive(Debug, Error)]
+#[non_exhaustive]
+#[error("No applicable canister ID for regtest")]
+pub struct BitcoinCanisterAttachError;
+
 impl<'agent> Deref for BitcoinCanister<'agent> {
     type Target = Canister<'agent>;
     fn deref(&self) -> &Self::Target {
@@ -54,15 +62,14 @@ impl<'agent> BitcoinCanister<'agent> {
         Self::for_network(agent, BitcoinNetwork::Testnet).expect("valid network")
     }
     /// Create a `BitcoinCanister` interface for the specified Bitcoin network on the IC mainnet. Errors if `Regtest` is specified.
-    pub fn for_network(agent: &'agent Agent, network: BitcoinNetwork) -> Result<Self, AgentError> {
+    pub fn for_network(
+        agent: &'agent Agent,
+        network: BitcoinNetwork,
+    ) -> Result<Self, BitcoinCanisterAttachError> {
         let canister_id = match network {
             BitcoinNetwork::Mainnet => MAINNET_ID,
             BitcoinNetwork::Testnet => TESTNET_ID,
-            BitcoinNetwork::Regtest => {
-                return Err(AgentError::MessageError(
-                    "No applicable canister ID for regtest".to_string(),
-                ))
-            }
+            BitcoinNetwork::Regtest => return Err(BitcoinCanisterAttachError),
         };
         Ok(Self::create(agent, canister_id, network))
     }
@@ -73,7 +80,7 @@ impl<'agent> BitcoinCanister<'agent> {
         &self,
         address: &str,
         min_confirmations: Option<u32>,
-    ) -> impl 'agent + AsyncCall<Value = (u64,)> {
+    ) -> impl 'agent + AsyncCall<Value = (u64,), Error = BaseError> {
         #[derive(CandidType)]
         struct In<'a> {
             address: &'a str,
@@ -95,7 +102,7 @@ impl<'agent> BitcoinCanister<'agent> {
         &self,
         address: &str,
         min_confirmations: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (u64,)> {
+    ) -> impl 'agent + SyncCall<Value = (u64,), Error = BaseError> {
         self.query("bitcoin_get_balance_query")
             .with_arg(GetBalance {
                 address,
@@ -114,7 +121,7 @@ impl<'agent> BitcoinCanister<'agent> {
         &self,
         address: &str,
         filter: Option<UtxosFilter>,
-    ) -> impl 'agent + AsyncCall<Value = (GetUtxosResponse,)> {
+    ) -> impl 'agent + AsyncCall<Value = (GetUtxosResponse,), Error = BaseError> {
         self.update("bitcoin_get_utxos")
             .with_arg(GetUtxos {
                 address,
@@ -133,7 +140,7 @@ impl<'agent> BitcoinCanister<'agent> {
         &self,
         address: &str,
         filter: Option<UtxosFilter>,
-    ) -> impl 'agent + SyncCall<Value = (GetUtxosResponse,)> {
+    ) -> impl 'agent + SyncCall<Value = (GetUtxosResponse,), Error = BaseError> {
         self.query("bitcoin_get_utxos_query")
             .with_arg(GetUtxos {
                 address,
@@ -145,7 +152,9 @@ impl<'agent> BitcoinCanister<'agent> {
 
     /// Gets the transaction fee percentiles for the last 10,000 transactions. In the returned vector, `v[i]` is the `i`th percentile fee,
     /// measured in millisatoshis/vbyte, and `v[0]` is the smallest fee.
-    pub fn get_current_fee_percentiles(&self) -> impl 'agent + AsyncCall<Value = (Vec<u64>,)> {
+    pub fn get_current_fee_percentiles(
+        &self,
+    ) -> impl 'agent + AsyncCall<Value = (Vec<u64>,), Error = BaseError> {
         #[derive(CandidType)]
         struct In {
             network: BitcoinNetwork,
@@ -162,7 +171,7 @@ impl<'agent> BitcoinCanister<'agent> {
         &self,
         start_height: u32,
         end_height: Option<u32>,
-    ) -> impl 'agent + AsyncCall<Value = (GetBlockHeadersResponse,)> {
+    ) -> impl 'agent + AsyncCall<Value = (GetBlockHeadersResponse,), Error = BaseError> {
         #[derive(CandidType)]
         struct In {
             start_height: u32,
@@ -176,7 +185,10 @@ impl<'agent> BitcoinCanister<'agent> {
             .build()
     }
     /// Submits a new Bitcoin transaction. No guarantees are made about the outcome.
-    pub fn send_transaction(&self, transaction: Vec<u8>) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn send_transaction(
+        &self,
+        transaction: Vec<u8>,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType, Deserialize)]
         struct In {
             network: BitcoinNetwork,
diff --git a/ic-utils/src/interfaces/http_request.rs b/ic-utils/src/interfaces/http_request.rs
index ab7e7363..15186376 100644
--- a/ic-utils/src/interfaces/http_request.rs
+++ b/ic-utils/src/interfaces/http_request.rs
@@ -2,6 +2,7 @@
 
 use crate::{
     call::{AsyncCall, SyncCall},
+    error::BaseError,
     Canister,
 };
 use candid::{
@@ -409,7 +410,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         >,
         body: impl AsRef<[u8]>,
         certificate_version: Option<&u16>,
-    ) -> impl 'agent + SyncCall<Value = (HttpResponse,)> {
+    ) -> impl 'agent + SyncCall<Value = (HttpResponse,), Error = BaseError> {
         self.http_request_custom(
             method.as_ref(),
             url.as_ref(),
@@ -428,7 +429,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         headers: H,
         body: &[u8],
         certificate_version: Option<&u16>,
-    ) -> impl 'agent + SyncCall<Value = (HttpResponse<T, C>,)>
+    ) -> impl 'agent + SyncCall<Value = (HttpResponse<T, C>,), Error = BaseError>
     where
         H: 'agent + Send + Sync + Clone + ExactSizeIterator<Item = HeaderField<'agent>>,
         T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
@@ -453,7 +454,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         url: impl AsRef<str>,
         headers: impl 'agent + Send + Sync + Clone + ExactSizeIterator<Item = HeaderField<'agent>>,
         body: impl AsRef<[u8]>,
-    ) -> impl 'agent + AsyncCall<Value = (HttpResponse,)> {
+    ) -> impl 'agent + AsyncCall<Value = (HttpResponse,), Error = BaseError> {
         self.http_request_update_custom(method.as_ref(), url.as_ref(), headers, body.as_ref())
     }
 
@@ -466,7 +467,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         url: &str,
         headers: H,
         body: &[u8],
-    ) -> impl 'agent + AsyncCall<Value = (HttpResponse<T, C>,)>
+    ) -> impl 'agent + AsyncCall<Value = (HttpResponse<T, C>,), Error = BaseError>
     where
         H: 'agent + Send + Sync + Clone + ExactSizeIterator<Item = HeaderField<'agent>>,
         T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
@@ -487,7 +488,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         &'canister self,
         method: impl AsRef<str>,
         token: Token,
-    ) -> impl 'agent + SyncCall<Value = (StreamingCallbackHttpResponse,)> {
+    ) -> impl 'agent + SyncCall<Value = (StreamingCallbackHttpResponse,), Error = BaseError> {
         self.query(method.as_ref()).with_value_arg(token.0).build()
     }
 
@@ -497,7 +498,7 @@ impl<'agent> HttpRequestCanister<'agent> {
         &'canister self,
         method: impl AsRef<str>,
         token: T,
-    ) -> impl 'agent + SyncCall<Value = (StreamingCallbackHttpResponse<T>,)>
+    ) -> impl 'agent + SyncCall<Value = (StreamingCallbackHttpResponse<T>,), Error = BaseError>
     where
         T: 'agent + Send + Sync + CandidType + for<'de> Deserialize<'de>,
     {
diff --git a/ic-utils/src/interfaces/management_canister.rs b/ic-utils/src/interfaces/management_canister.rs
index d498d6dc..90b3cbd8 100644
--- a/ic-utils/src/interfaces/management_canister.rs
+++ b/ic-utils/src/interfaces/management_canister.rs
@@ -4,6 +4,7 @@
 
 use crate::{
     call::{AsyncCall, SyncCall},
+    error::BaseError,
     Canister,
 };
 use candid::{CandidType, Deserialize, Nat};
@@ -267,7 +268,7 @@ impl<'agent> ManagementCanister<'agent> {
     pub fn canister_status(
         &self,
         canister_id: &Principal,
-    ) -> impl 'agent + AsyncCall<Value = (StatusCallResult,)> {
+    ) -> impl 'agent + AsyncCall<Value = (StatusCallResult,), Error = BaseError> {
         #[derive(CandidType)]
         struct In {
             canister_id: Principal,
@@ -289,7 +290,10 @@ impl<'agent> ManagementCanister<'agent> {
 
     /// This method deposits the cycles included in this call into the specified canister.
     /// Only the controller of the canister can deposit cycles.
-    pub fn deposit_cycles(&self, canister_id: &Principal) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn deposit_cycles(
+        &self,
+        canister_id: &Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -304,7 +308,10 @@ impl<'agent> ManagementCanister<'agent> {
     }
 
     /// Deletes a canister.
-    pub fn delete_canister(&self, canister_id: &Principal) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn delete_canister(
+        &self,
+        canister_id: &Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -326,7 +333,7 @@ impl<'agent> ManagementCanister<'agent> {
         &self,
         canister_id: &Principal,
         amount: u64,
-    ) -> impl 'agent + AsyncCall<Value = ()> {
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -345,14 +352,17 @@ impl<'agent> ManagementCanister<'agent> {
     /// This method takes no input and returns 32 pseudo-random bytes to the caller.
     /// The return value is unknown to any part of the IC at time of the submission of this call.
     /// A new return value is generated for each call to this method.
-    pub fn raw_rand(&self) -> impl 'agent + AsyncCall<Value = (Vec<u8>,)> {
+    pub fn raw_rand(&self) -> impl 'agent + AsyncCall<Value = (Vec<u8>,), Error = BaseError> {
         self.update(MgmtMethod::RawRand.as_ref())
             .build()
             .map(|result: (Vec<u8>,)| (result.0,))
     }
 
     /// Starts a canister.
-    pub fn start_canister(&self, canister_id: &Principal) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn start_canister(
+        &self,
+        canister_id: &Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -367,7 +377,10 @@ impl<'agent> ManagementCanister<'agent> {
     }
 
     /// Stop a canister.
-    pub fn stop_canister(&self, canister_id: &Principal) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn stop_canister(
+        &self,
+        canister_id: &Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -388,7 +401,10 @@ impl<'agent> ManagementCanister<'agent> {
     /// Outstanding responses to the canister will not be processed, even if they arrive after code has been installed again.
     /// The canister is now empty. In particular, any incoming or queued calls will be rejected.
     //// A canister after uninstalling retains its cycles balance, controller, status, and allocations.
-    pub fn uninstall_code(&self, canister_id: &Principal) -> impl 'agent + AsyncCall<Value = ()> {
+    pub fn uninstall_code(
+        &self,
+        canister_id: &Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument {
             canister_id: Principal,
@@ -424,7 +440,7 @@ impl<'agent> ManagementCanister<'agent> {
         &self,
         canister_id: &Principal,
         chunk: &[u8],
-    ) -> impl 'agent + AsyncCall<Value = (UploadChunkResult,)> {
+    ) -> impl 'agent + AsyncCall<Value = (UploadChunkResult,), Error = BaseError> {
         #[derive(CandidType, Deserialize)]
         struct Argument<'a> {
             canister_id: Principal,
@@ -445,7 +461,7 @@ impl<'agent> ManagementCanister<'agent> {
     pub fn clear_chunk_store(
         &self,
         canister_id: &Principal,
-    ) -> impl 'agent + AsyncCall<Value = ()> {
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument<'a> {
             canister_id: &'a Principal,
@@ -460,7 +476,7 @@ impl<'agent> ManagementCanister<'agent> {
     pub fn stored_chunks(
         &self,
         canister_id: &Principal,
-    ) -> impl 'agent + AsyncCall<Value = (StoreChunksResult,)> {
+    ) -> impl 'agent + AsyncCall<Value = (StoreChunksResult,), Error = BaseError> {
         #[derive(CandidType)]
         struct Argument<'a> {
             canister_id: &'a Principal,
@@ -497,7 +513,7 @@ impl<'agent> ManagementCanister<'agent> {
     pub fn fetch_canister_logs(
         &self,
         canister_id: &Principal,
-    ) -> impl 'agent + SyncCall<Value = (FetchCanisterLogsResponse,)> {
+    ) -> impl 'agent + SyncCall<Value = (FetchCanisterLogsResponse,), Error = BaseError> {
         #[derive(CandidType)]
         struct In {
             canister_id: Principal,
@@ -519,7 +535,7 @@ impl<'agent> ManagementCanister<'agent> {
         &self,
         canister_id: &Principal,
         replace_snapshot: Option<&[u8]>,
-    ) -> impl 'agent + AsyncCall<Value = (Snapshot,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Snapshot,), Error = BaseError> {
         #[derive(CandidType)]
         struct In<'a> {
             canister_id: Principal,
@@ -541,7 +557,7 @@ impl<'agent> ManagementCanister<'agent> {
         &self,
         canister_id: &Principal,
         snapshot_id: &[u8],
-    ) -> impl 'agent + AsyncCall<Value = ()> {
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct In<'a> {
             canister_id: Principal,
@@ -562,7 +578,7 @@ impl<'agent> ManagementCanister<'agent> {
     pub fn list_canister_snapshots(
         &self,
         canister_id: &Principal,
-    ) -> impl 'agent + AsyncCall<Value = (Vec<Snapshot>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Vec<Snapshot>,), Error = BaseError> {
         #[derive(CandidType)]
         struct In {
             canister_id: Principal,
@@ -580,7 +596,7 @@ impl<'agent> ManagementCanister<'agent> {
         &self,
         canister_id: &Principal,
         snapshot_id: &[u8],
-    ) -> impl 'agent + AsyncCall<Value = ()> {
+    ) -> impl 'agent + AsyncCall<Value = (), Error = BaseError> {
         #[derive(CandidType)]
         struct In<'a> {
             canister_id: Principal,
diff --git a/ic-utils/src/interfaces/management_canister/builders.rs b/ic-utils/src/interfaces/management_canister/builders.rs
index 834bcf5b..0bc65682 100644
--- a/ic-utils/src/interfaces/management_canister/builders.rs
+++ b/ic-utils/src/interfaces/management_canister/builders.rs
@@ -4,8 +4,13 @@
 pub use super::attributes::{
     ComputeAllocation, FreezingThreshold, MemoryAllocation, ReservedCyclesLimit, WasmMemoryLimit,
 };
+use super::attributes::{
+    ComputeAllocationError, FreezingThresholdError, MemoryAllocationError,
+    ReservedCyclesLimitError, WasmMemoryLimitError,
+};
 use super::{ChunkHash, LogVisibility, ManagementCanister};
 use crate::call::CallFuture;
+use crate::error::{impl_canister_error, BaseError};
 use crate::{
     call::AsyncCall, canister::Argument, interfaces::management_canister::MgmtMethod, Canister,
 };
@@ -16,8 +21,10 @@ use futures_util::{
     stream::{self, FuturesUnordered},
     FutureExt, Stream, StreamExt, TryStreamExt,
 };
+use ic_agent::export::PrincipalError;
 use ic_agent::{agent::CallResponse, export::Principal, AgentError};
 use sha2::{Digest, Sha256};
+use std::convert::Infallible;
 use std::{
     collections::BTreeSet,
     convert::{From, TryInto},
@@ -25,6 +32,7 @@ use std::{
     pin::Pin,
     str::FromStr,
 };
+use thiserror::Error;
 
 /// The set of possible canister settings. Similar to [`DefiniteCanisterSettings`](super::DefiniteCanisterSettings),
 /// but all the fields are optional.
@@ -96,14 +104,14 @@ pub struct CanisterSettings {
 pub struct CreateCanisterBuilder<'agent, 'canister: 'agent> {
     canister: &'canister Canister<'agent>,
     effective_canister_id: Principal,
-    controllers: Option<Result<Vec<Principal>, AgentError>>,
-    compute_allocation: Option<Result<ComputeAllocation, AgentError>>,
-    memory_allocation: Option<Result<MemoryAllocation, AgentError>>,
-    freezing_threshold: Option<Result<FreezingThreshold, AgentError>>,
-    reserved_cycles_limit: Option<Result<ReservedCyclesLimit, AgentError>>,
-    wasm_memory_limit: Option<Result<WasmMemoryLimit, AgentError>>,
-    wasm_memory_threshold: Option<Result<WasmMemoryLimit, AgentError>>,
-    log_visibility: Option<Result<LogVisibility, AgentError>>,
+    controllers: Option<Result<Vec<Principal>, AttributeConversionError>>,
+    compute_allocation: Option<Result<ComputeAllocation, AttributeConversionError>>,
+    memory_allocation: Option<Result<MemoryAllocation, AttributeConversionError>>,
+    freezing_threshold: Option<Result<FreezingThreshold, AttributeConversionError>>,
+    reserved_cycles_limit: Option<Result<ReservedCyclesLimit, AttributeConversionError>>,
+    wasm_memory_limit: Option<Result<WasmMemoryLimit, AttributeConversionError>>,
+    wasm_memory_threshold: Option<Result<WasmMemoryLimit, AttributeConversionError>>,
+    log_visibility: Option<Result<LogVisibility, AttributeConversionError>>,
     is_provisional_create: bool,
     amount: Option<u128>,
     specified_id: Option<Principal>,
@@ -160,7 +168,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in an effective canister id for the update call.
     pub fn with_effective_canister_id<C, E>(self, effective_canister_id: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<Principal, Error = E>,
     {
         match effective_canister_id.try_into() {
@@ -176,17 +184,14 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the controller to default.
     pub fn with_optional_controller<C, E>(self, controller: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<Principal, Error = E>,
     {
-        let controller_to_add: Option<Result<Principal, _>> = controller.map(|ca| {
-            ca.try_into()
-                .map_err(|e| AgentError::MessageError(format!("{e}")))
-        });
+        let controller_to_add: Option<Result<Principal, _>> = controller.map(|ca| ca.try_into());
         let controllers: Option<Result<Vec<Principal>, _>> =
             match (controller_to_add, self.controllers) {
                 (_, Some(Err(sticky))) => Some(Err(sticky)),
-                (Some(Err(e)), _) => Some(Err(e)),
+                (Some(Err(e)), _) => Some(Err(e.into())),
                 (None, _) => None,
                 (Some(Ok(controller)), Some(Ok(controllers))) => {
                     let mut controllers = controllers;
@@ -204,7 +209,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a designated controller for the canister.
     pub fn with_controller<C, E>(self, controller: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<Principal, Error = E>,
     {
         self.with_optional_controller(Some(controller))
@@ -214,14 +219,11 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the compute allocation to default.
     pub fn with_optional_compute_allocation<C, E>(self, compute_allocation: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ComputeAllocation, Error = E>,
     {
         Self {
-            compute_allocation: compute_allocation.map(|ca| {
-                ca.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            compute_allocation: compute_allocation.map(|ca| ca.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -229,7 +231,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a compute allocation value for the canister.
     pub fn with_compute_allocation<C, E>(self, compute_allocation: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ComputeAllocation, Error = E>,
     {
         self.with_optional_compute_allocation(Some(compute_allocation))
@@ -239,14 +241,11 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the memory allocation to default.
     pub fn with_optional_memory_allocation<E, C>(self, memory_allocation: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<MemoryAllocation, Error = E>,
     {
         Self {
-            memory_allocation: memory_allocation.map(|ma| {
-                ma.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            memory_allocation: memory_allocation.map(|ma| ma.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -254,7 +253,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a memory allocation value for the canister.
     pub fn with_memory_allocation<C, E>(self, memory_allocation: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<MemoryAllocation, Error = E>,
     {
         self.with_optional_memory_allocation(Some(memory_allocation))
@@ -264,14 +263,11 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the freezing threshold to default.
     pub fn with_optional_freezing_threshold<E, C>(self, freezing_threshold: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<FreezingThreshold, Error = E>,
     {
         Self {
-            freezing_threshold: freezing_threshold.map(|ma| {
-                ma.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            freezing_threshold: freezing_threshold.map(|ma| ma.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -279,7 +275,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a freezing threshold value for the canister.
     pub fn with_freezing_threshold<C, E>(self, freezing_threshold: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<FreezingThreshold, Error = E>,
     {
         self.with_optional_freezing_threshold(Some(freezing_threshold))
@@ -288,7 +284,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a reserved cycles limit value for the canister.
     pub fn with_reserved_cycles_limit<C, E>(self, limit: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ReservedCyclesLimit, Error = E>,
     {
         self.with_optional_reserved_cycles_limit(Some(limit))
@@ -298,15 +294,11 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will create the canister with the default limit.
     pub fn with_optional_reserved_cycles_limit<E, C>(self, limit: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ReservedCyclesLimit, Error = E>,
     {
         Self {
-            reserved_cycles_limit: limit.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            reserved_cycles_limit: limit.map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -314,7 +306,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a Wasm memory limit value for the canister.
     pub fn with_wasm_memory_limit<C, E>(self, wasm_memory_limit: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         self.with_optional_wasm_memory_limit(Some(wasm_memory_limit))
@@ -324,15 +316,11 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the Wasm memory limit to default.
     pub fn with_optional_wasm_memory_limit<E, C>(self, wasm_memory_limit: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         Self {
-            wasm_memory_limit: wasm_memory_limit.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            wasm_memory_limit: wasm_memory_limit.map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -340,7 +328,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a Wasm memory threshold value for the canister.
     pub fn with_wasm_memory_threshold<C, E>(self, wasm_memory_threshold: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         self.with_optional_wasm_memory_threshold(Some(wasm_memory_threshold))
@@ -350,15 +338,12 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the Wasm memory threshold to default.
     pub fn with_optional_wasm_memory_threshold<E, C>(self, wasm_memory_threshold: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         Self {
-            wasm_memory_threshold: wasm_memory_threshold.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            wasm_memory_threshold: wasm_memory_threshold
+                .map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -366,7 +351,7 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// Pass in a log visibility setting for the canister.
     pub fn with_log_visibility<C, E>(self, log_visibility: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<LogVisibility, Error = E>,
     {
         self.with_optional_log_visibility(Some(log_visibility))
@@ -376,59 +361,61 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     /// it will revert the log visibility to default.
     pub fn with_optional_log_visibility<E, C>(self, log_visibility: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<LogVisibility, Error = E>,
     {
         Self {
-            log_visibility: log_visibility.map(|visibility| {
-                visibility
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            log_visibility: log_visibility
+                .map(|visibility| visibility.try_into().map_err(From::from)),
             ..self
         }
     }
 
     /// Create an [`AsyncCall`] implementation that, when called, will create a
     /// canister.
-    pub fn build(self) -> Result<impl 'agent + AsyncCall<Value = (Principal,)>, AgentError> {
+    pub fn build(
+        self,
+    ) -> Result<
+        impl 'agent + AsyncCall<Value = (Principal,), Error = CanisterManagementError>,
+        AttributeConversionError,
+    > {
         let controllers = match self.controllers {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(x),
             None => None,
         };
         let compute_allocation = match self.compute_allocation {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u8::from(x))),
             None => None,
         };
         let memory_allocation = match self.memory_allocation {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let freezing_threshold = match self.freezing_threshold {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let reserved_cycles_limit = match self.reserved_cycles_limit {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u128::from(x))),
             None => None,
         };
         let wasm_memory_limit = match self.wasm_memory_limit {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let wasm_memory_threshold = match self.wasm_memory_threshold {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let log_visibility = match self.log_visibility {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(x),
             None => None,
         };
@@ -460,12 +447,12 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
                 specified_id: self.specified_id,
             };
             self.canister
-                .update(MgmtMethod::ProvisionalCreateCanisterWithCycles.as_ref())
+                .update_(MgmtMethod::ProvisionalCreateCanisterWithCycles.as_ref())
                 .with_arg(in_arg)
                 .with_effective_canister_id(self.effective_canister_id)
         } else {
             self.canister
-                .update(MgmtMethod::CreateCanister.as_ref())
+                .update_(MgmtMethod::CreateCanister.as_ref())
                 .with_arg(CanisterSettings {
                     controllers,
                     compute_allocation,
@@ -485,12 +472,12 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<(Principal,)>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<(Principal,)>, CanisterManagementError> {
         self.build()?.call().await
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<(Principal,), AgentError> {
+    pub async fn call_and_wait(self) -> Result<(Principal,), CanisterManagementError> {
         self.build()?.call_and_wait().await
     }
 }
@@ -499,25 +486,42 @@ impl<'agent, 'canister: 'agent> CreateCanisterBuilder<'agent, 'canister> {
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
 impl<'agent, 'canister: 'agent> AsyncCall for CreateCanisterBuilder<'agent, 'canister> {
     type Value = (Principal,);
+    type Error = CanisterManagementError;
 
-    async fn call(self) -> Result<CallResponse<(Principal,)>, AgentError> {
+    async fn call(self) -> Result<CallResponse<(Principal,)>, CanisterManagementError> {
         self.build()?.call().await
     }
 
-    async fn call_and_wait(self) -> Result<(Principal,), AgentError> {
+    async fn call_and_wait(self) -> Result<(Principal,), CanisterManagementError> {
         self.build()?.call_and_wait().await
     }
 }
 
 impl<'agent, 'canister: 'agent> IntoFuture for CreateCanisterBuilder<'agent, 'canister> {
-    type IntoFuture = CallFuture<'agent, (Principal,)>;
-    type Output = Result<(Principal,), AgentError>;
+    type IntoFuture = CallFuture<'agent, (Principal,), CanisterManagementError>;
+    type Output = Result<(Principal,), CanisterManagementError>;
 
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
     }
 }
 
+/// An error that can occur when performing an operation that updates canister settings.
+#[derive(Debug, Error)]
+pub enum CanisterManagementError {
+    /// An error occurred when encoding/decoding Candid.
+    #[error("{0}")]
+    Candid(#[from] candid::Error),
+    /// An error occurred in the agent.
+    #[error("{0}")]
+    Agent(#[from] AgentError),
+    /// An error occurred parsing a canister setting.
+    #[error(transparent)]
+    Conversion(#[from] AttributeConversionError),
+}
+
+impl_canister_error!(CanisterManagementError);
+
 #[derive(Clone, Debug, Deserialize, PartialEq, Eq, Hash, CandidType, Copy)]
 /// Wasm main memory retention on upgrades.
 /// Currently used to specify the persistence of Wasm main memory.
@@ -643,10 +647,12 @@ impl<'agent, 'canister: 'agent> InstallCodeBuilder<'agent, 'canister> {
 
     /// Create an [`AsyncCall`] implementation that, when called, will install the
     /// canister.
-    pub fn build(self) -> Result<impl 'agent + AsyncCall<Value = ()>, AgentError> {
+    pub fn build(
+        self,
+    ) -> Result<impl 'agent + AsyncCall<Value = (), Error = BaseError>, candid::Error> {
         Ok(self
             .canister
-            .update(MgmtMethod::InstallCode.as_ref())
+            .update_(MgmtMethod::InstallCode.as_ref())
             .with_arg(CanisterInstall {
                 mode: self.mode.unwrap_or(InstallMode::Install),
                 canister_id: self.canister_id,
@@ -658,12 +664,12 @@ impl<'agent, 'canister: 'agent> InstallCodeBuilder<'agent, 'canister> {
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<()>, BaseError> {
         self.build()?.call().await
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<(), AgentError> {
+    pub async fn call_and_wait(self) -> Result<(), BaseError> {
         self.build()?.call_and_wait().await
     }
 }
@@ -672,19 +678,20 @@ impl<'agent, 'canister: 'agent> InstallCodeBuilder<'agent, 'canister> {
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
 impl<'agent, 'canister: 'agent> AsyncCall for InstallCodeBuilder<'agent, 'canister> {
     type Value = ();
+    type Error = BaseError;
 
-    async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    async fn call(self) -> Result<CallResponse<()>, BaseError> {
         self.build()?.call().await
     }
 
-    async fn call_and_wait(self) -> Result<(), AgentError> {
+    async fn call_and_wait(self) -> Result<(), BaseError> {
         self.build()?.call_and_wait().await
     }
 }
 
 impl<'agent, 'canister: 'agent> IntoFuture for InstallCodeBuilder<'agent, 'canister> {
-    type IntoFuture = CallFuture<'agent, ()>;
-    type Output = Result<(), AgentError>;
+    type IntoFuture = CallFuture<'agent, (), BaseError>;
+    type Output = Result<(), BaseError>;
 
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
@@ -761,7 +768,9 @@ impl<'agent: 'canister, 'canister> InstallChunkedCodeBuilder<'agent, 'canister>
     }
 
     /// Create an [`AsyncCall`] implementation that, when called, will install the canister.
-    pub fn build(self) -> Result<impl 'agent + AsyncCall<Value = ()>, AgentError> {
+    pub fn build(
+        self,
+    ) -> Result<impl 'agent + AsyncCall<Value = (), Error = BaseError>, candid::Error> {
         #[derive(CandidType)]
         struct In {
             mode: InstallMode,
@@ -798,12 +807,12 @@ impl<'agent: 'canister, 'canister> InstallChunkedCodeBuilder<'agent, 'canister>
     }
 
     /// Make the call. This is equivalent to [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<()>, BaseError> {
         self.build()?.call().await
     }
 
     /// Make the call. This is equivalent to [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<(), AgentError> {
+    pub async fn call_and_wait(self) -> Result<(), BaseError> {
         self.build()?.call_and_wait().await
     }
 }
@@ -812,19 +821,20 @@ impl<'agent: 'canister, 'canister> InstallChunkedCodeBuilder<'agent, 'canister>
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
 impl<'agent, 'canister: 'agent> AsyncCall for InstallChunkedCodeBuilder<'agent, 'canister> {
     type Value = ();
+    type Error = BaseError;
 
-    async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    async fn call(self) -> Result<CallResponse<()>, BaseError> {
         self.call().await
     }
 
-    async fn call_and_wait(self) -> Result<(), AgentError> {
+    async fn call_and_wait(self) -> Result<(), BaseError> {
         self.call_and_wait().await
     }
 }
 
 impl<'agent, 'canister: 'agent> IntoFuture for InstallChunkedCodeBuilder<'agent, 'canister> {
-    type IntoFuture = CallFuture<'agent, ()>;
-    type Output = Result<(), AgentError>;
+    type IntoFuture = CallFuture<'agent, (), BaseError>;
+    type Output = Result<(), BaseError>;
 
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
@@ -893,7 +903,7 @@ impl<'agent: 'canister, 'canister: 'builder, 'builder> InstallBuilder<'agent, 'c
 
     /// Invoke the installation process. This may result in many calls which may take several seconds;
     /// use [`call_and_wait_with_progress`](Self::call_and_wait_with_progress) if you want progress reporting.
-    pub async fn call_and_wait(self) -> Result<(), AgentError> {
+    pub async fn call_and_wait(self) -> Result<(), BaseError> {
         self.call_and_wait_with_progress()
             .await
             .try_for_each(|_| ready(Ok(())))
@@ -905,7 +915,7 @@ impl<'agent: 'canister, 'canister: 'builder, 'builder> InstallBuilder<'agent, 'c
     /// There are exactly [`size_hint().0`](Stream::size_hint) steps.
     pub async fn call_and_wait_with_progress(
         self,
-    ) -> impl Stream<Item = Result<(), AgentError>> + 'builder {
+    ) -> impl Stream<Item = Result<(), BaseError>> + 'builder {
         let stream_res = /* try { */ async move {
             let arg = self.arg.serialize()?;
             let stream: BoxStream<'_, _> =
@@ -983,8 +993,8 @@ impl<'agent: 'canister, 'canister: 'builder, 'builder> InstallBuilder<'agent, 'c
 impl<'agent: 'canister, 'canister: 'builder, 'builder> IntoFuture
     for InstallBuilder<'agent, 'canister, 'builder>
 {
-    type IntoFuture = CallFuture<'builder, ()>;
-    type Output = Result<(), AgentError>;
+    type IntoFuture = CallFuture<'builder, (), BaseError>;
+    type Output = Result<(), BaseError>;
 
     fn into_future(self) -> Self::IntoFuture {
         Box::pin(self.call_and_wait())
@@ -996,14 +1006,14 @@ impl<'agent: 'canister, 'canister: 'builder, 'builder> IntoFuture
 pub struct UpdateCanisterBuilder<'agent, 'canister: 'agent> {
     canister: &'canister Canister<'agent>,
     canister_id: Principal,
-    controllers: Option<Result<Vec<Principal>, AgentError>>,
-    compute_allocation: Option<Result<ComputeAllocation, AgentError>>,
-    memory_allocation: Option<Result<MemoryAllocation, AgentError>>,
-    freezing_threshold: Option<Result<FreezingThreshold, AgentError>>,
-    reserved_cycles_limit: Option<Result<ReservedCyclesLimit, AgentError>>,
-    wasm_memory_limit: Option<Result<WasmMemoryLimit, AgentError>>,
-    wasm_memory_threshold: Option<Result<WasmMemoryLimit, AgentError>>,
-    log_visibility: Option<Result<LogVisibility, AgentError>>,
+    controllers: Option<Result<Vec<Principal>, AttributeConversionError>>,
+    compute_allocation: Option<Result<ComputeAllocation, AttributeConversionError>>,
+    memory_allocation: Option<Result<MemoryAllocation, AttributeConversionError>>,
+    freezing_threshold: Option<Result<FreezingThreshold, AttributeConversionError>>,
+    reserved_cycles_limit: Option<Result<ReservedCyclesLimit, AttributeConversionError>>,
+    wasm_memory_limit: Option<Result<WasmMemoryLimit, AttributeConversionError>>,
+    wasm_memory_threshold: Option<Result<WasmMemoryLimit, AttributeConversionError>>,
+    log_visibility: Option<Result<LogVisibility, AttributeConversionError>>,
 }
 
 impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
@@ -1027,13 +1037,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// it will revert the controller to default.
     pub fn with_optional_controller<C, E>(self, controller: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<Principal, Error = E>,
     {
-        let controller_to_add: Option<Result<Principal, _>> = controller.map(|ca| {
-            ca.try_into()
-                .map_err(|e| AgentError::MessageError(format!("{e}")))
-        });
+        let controller_to_add: Option<Result<Principal, _>> =
+            controller.map(|ca| ca.try_into().map_err(From::from));
         let controllers: Option<Result<Vec<Principal>, _>> =
             match (controller_to_add, self.controllers) {
                 (_, Some(Err(sticky))) => Some(Err(sticky)),
@@ -1056,7 +1064,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a designated controller for the canister.
     pub fn with_controller<C, E>(self, controller: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<Principal, Error = E>,
     {
         self.with_optional_controller(Some(controller))
@@ -1066,14 +1074,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// it will revert the compute allocation to default.
     pub fn with_optional_compute_allocation<C, E>(self, compute_allocation: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ComputeAllocation, Error = E>,
     {
         Self {
-            compute_allocation: compute_allocation.map(|ca| {
-                ca.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            compute_allocation: compute_allocation.map(|ca| ca.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1081,7 +1086,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a compute allocation value for the canister.
     pub fn with_compute_allocation<C, E>(self, compute_allocation: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ComputeAllocation, Error = E>,
     {
         self.with_optional_compute_allocation(Some(compute_allocation))
@@ -1091,14 +1096,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// it will revert the memory allocation to default.
     pub fn with_optional_memory_allocation<E, C>(self, memory_allocation: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<MemoryAllocation, Error = E>,
     {
         Self {
-            memory_allocation: memory_allocation.map(|ma| {
-                ma.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            memory_allocation: memory_allocation.map(|ma| ma.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1106,7 +1108,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a memory allocation value for the canister.
     pub fn with_memory_allocation<C, E>(self, memory_allocation: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<MemoryAllocation, Error = E>,
     {
         self.with_optional_memory_allocation(Some(memory_allocation))
@@ -1116,14 +1118,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// it will revert the freezing threshold to default.
     pub fn with_optional_freezing_threshold<E, C>(self, freezing_threshold: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<FreezingThreshold, Error = E>,
     {
         Self {
-            freezing_threshold: freezing_threshold.map(|ma| {
-                ma.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            freezing_threshold: freezing_threshold.map(|ma| ma.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1131,7 +1130,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a freezing threshold value for the canister.
     pub fn with_freezing_threshold<C, E>(self, freezing_threshold: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<FreezingThreshold, Error = E>,
     {
         self.with_optional_freezing_threshold(Some(freezing_threshold))
@@ -1140,7 +1139,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a reserved cycles limit value for the canister.
     pub fn with_reserved_cycles_limit<C, E>(self, limit: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ReservedCyclesLimit, Error = E>,
     {
         self.with_optional_reserved_cycles_limit(Some(limit))
@@ -1150,14 +1149,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// If this is [`None`], leaves the reserved cycles limit unchanged.
     pub fn with_optional_reserved_cycles_limit<E, C>(self, limit: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<ReservedCyclesLimit, Error = E>,
     {
         Self {
-            reserved_cycles_limit: limit.map(|ma| {
-                ma.try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            reserved_cycles_limit: limit.map(|ma| ma.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1165,7 +1161,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a Wasm memory limit value for the canister.
     pub fn with_wasm_memory_limit<C, E>(self, wasm_memory_limit: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         self.with_optional_wasm_memory_limit(Some(wasm_memory_limit))
@@ -1175,15 +1171,11 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// leaves the Wasm memory limit unchanged.
     pub fn with_optional_wasm_memory_limit<E, C>(self, wasm_memory_limit: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         Self {
-            wasm_memory_limit: wasm_memory_limit.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            wasm_memory_limit: wasm_memory_limit.map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1191,7 +1183,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a Wasm memory threshold value for the canister.
     pub fn with_wasm_memory_threshold<C, E>(self, wasm_memory_threshold: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         self.with_optional_wasm_memory_threshold(Some(wasm_memory_threshold))
@@ -1201,15 +1193,12 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// leaves the memory threshold unchanged.
     pub fn with_optional_wasm_memory_threshold<E, C>(self, wasm_memory_threshold: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<WasmMemoryLimit, Error = E>,
     {
         Self {
-            wasm_memory_threshold: wasm_memory_threshold.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            wasm_memory_threshold: wasm_memory_threshold
+                .map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
@@ -1217,7 +1206,7 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// Pass in a log visibility setting for the canister.
     pub fn with_log_visibility<C, E>(self, log_visibility: C) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<LogVisibility, Error = E>,
     {
         self.with_optional_log_visibility(Some(log_visibility))
@@ -1227,22 +1216,23 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     /// leaves the log visibility unchanged.
     pub fn with_optional_log_visibility<E, C>(self, log_visibility: Option<C>) -> Self
     where
-        E: std::fmt::Display,
+        AttributeConversionError: From<E>,
         C: TryInto<LogVisibility, Error = E>,
     {
         Self {
-            log_visibility: log_visibility.map(|limit| {
-                limit
-                    .try_into()
-                    .map_err(|e| AgentError::MessageError(format!("{e}")))
-            }),
+            log_visibility: log_visibility.map(|limit| limit.try_into().map_err(From::from)),
             ..self
         }
     }
 
     /// Create an [`AsyncCall`] implementation that, when called, will update a
     /// canisters settings.
-    pub fn build(self) -> Result<impl 'agent + AsyncCall<Value = ()>, AgentError> {
+    pub fn build(
+        self,
+    ) -> Result<
+        impl 'agent + AsyncCall<Value = (), Error = CanisterManagementError>,
+        AttributeConversionError,
+    > {
         #[derive(CandidType)]
         struct In {
             canister_id: Principal,
@@ -1250,49 +1240,49 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
         }
 
         let controllers = match self.controllers {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(x),
             None => None,
         };
         let compute_allocation = match self.compute_allocation {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u8::from(x))),
             None => None,
         };
         let memory_allocation = match self.memory_allocation {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let freezing_threshold = match self.freezing_threshold {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let reserved_cycles_limit = match self.reserved_cycles_limit {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u128::from(x))),
             None => None,
         };
         let wasm_memory_limit = match self.wasm_memory_limit {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let wasm_memory_threshold = match self.wasm_memory_threshold {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(Nat::from(u64::from(x))),
             None => None,
         };
         let log_visibility = match self.log_visibility {
-            Some(Err(x)) => return Err(AgentError::MessageError(format!("{x}"))),
+            Some(Err(x)) => return Err(x),
             Some(Ok(x)) => Some(x),
             None => None,
         };
 
         Ok(self
             .canister
-            .update(MgmtMethod::UpdateSettings.as_ref())
+            .update_(MgmtMethod::UpdateSettings.as_ref())
             .with_arg(In {
                 canister_id: self.canister_id,
                 settings: CanisterSettings {
@@ -1311,12 +1301,12 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call`].
-    pub async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    pub async fn call(self) -> Result<CallResponse<()>, CanisterManagementError> {
         self.build()?.call().await
     }
 
     /// Make a call. This is equivalent to the [`AsyncCall::call_and_wait`].
-    pub async fn call_and_wait(self) -> Result<(), AgentError> {
+    pub async fn call_and_wait(self) -> Result<(), CanisterManagementError> {
         self.build()?.call_and_wait().await
     }
 }
@@ -1325,18 +1315,19 @@ impl<'agent, 'canister: 'agent> UpdateCanisterBuilder<'agent, 'canister> {
 #[cfg_attr(not(target_family = "wasm"), async_trait)]
 impl<'agent, 'canister: 'agent> AsyncCall for UpdateCanisterBuilder<'agent, 'canister> {
     type Value = ();
-    async fn call(self) -> Result<CallResponse<()>, AgentError> {
+    type Error = CanisterManagementError;
+    async fn call(self) -> Result<CallResponse<()>, CanisterManagementError> {
         self.build()?.call().await
     }
 
-    async fn call_and_wait(self) -> Result<(), AgentError> {
+    async fn call_and_wait(self) -> Result<(), CanisterManagementError> {
         self.build()?.call_and_wait().await
     }
 }
 
 impl<'agent, 'canister: 'agent> IntoFuture for UpdateCanisterBuilder<'agent, 'canister> {
-    type IntoFuture = CallFuture<'agent, ()>;
-    type Output = Result<(), AgentError>;
+    type IntoFuture = CallFuture<'agent, (), CanisterManagementError>;
+    type Output = Result<(), CanisterManagementError>;
     fn into_future(self) -> Self::IntoFuture {
         AsyncCall::call_and_wait(self)
     }
@@ -1346,3 +1337,27 @@ impl<'agent, 'canister: 'agent> IntoFuture for UpdateCanisterBuilder<'agent, 'ca
 type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + Send + 'a>>;
 #[cfg(target_family = "wasm")]
 type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + 'a>>;
+
+/// Union of all the canister settings errors.
+#[allow(missing_docs)]
+#[derive(Debug, Error)]
+pub enum AttributeConversionError {
+    #[error(transparent)]
+    FreezingThreshold(#[from] FreezingThresholdError),
+    #[error(transparent)]
+    ComputeAllocation(#[from] ComputeAllocationError),
+    #[error(transparent)]
+    MemoryAllocation(#[from] MemoryAllocationError),
+    #[error(transparent)]
+    ReservedCyclesLimit(#[from] ReservedCyclesLimitError),
+    #[error(transparent)]
+    WasmMemoryLimit(#[from] WasmMemoryLimitError),
+    #[error(transparent)]
+    Principal(#[from] PrincipalError),
+}
+
+impl From<Infallible> for AttributeConversionError {
+    fn from(value: Infallible) -> Self {
+        match value {}
+    }
+}
diff --git a/ic-utils/src/interfaces/wallet.rs b/ic-utils/src/interfaces/wallet.rs
index 177b819a..fbd34fb7 100644
--- a/ic-utils/src/interfaces/wallet.rs
+++ b/ic-utils/src/interfaces/wallet.rs
@@ -3,6 +3,7 @@
 //! [cycles wallet]: https://github.com/dfinity/cycles-wallet
 
 use std::{
+    fmt::Display,
     future::{Future, IntoFuture},
     ops::Deref,
 };
@@ -10,6 +11,7 @@ use std::{
 use crate::{
     call::{AsyncCall, CallFuture, SyncCall},
     canister::Argument,
+    error::{impl_canister_error, BaseError},
     interfaces::management_canister::{
         attributes::{ComputeAllocation, FreezingThreshold, MemoryAllocation},
         builders::CanisterSettings,
@@ -18,9 +20,10 @@ use crate::{
 };
 use async_trait::async_trait;
 use candid::{decode_args, utils::ArgumentDecoder, CandidType, Deserialize, Nat};
-use ic_agent::{agent::CallResponse, export::Principal, Agent, AgentError};
+use ic_agent::{agent::CallResponse, agent_error::ErrorKind, export::Principal, Agent, AgentError};
 use once_cell::sync::Lazy;
 use semver::{Version, VersionReq};
+use thiserror::Error;
 
 const REPLICA_ERROR_NO_SUCH_QUERY_METHOD: &str = "has no query method 'wallet_api_version'";
 const IC_REF_ERROR_NO_SUCH_QUERY_METHOD: &str = "query method does not exist";
@@ -82,7 +85,9 @@ where
     }
 
     /// Creates an [`AsyncCall`] implementation that, when called, will forward the specified canister call.
-    pub fn build(self) -> Result<impl 'agent + AsyncCall<Value = Out>, AgentError> {
+    pub fn build(
+        self,
+    ) -> Result<impl 'agent + AsyncCall<Value = Out, Error = WalletError>, WalletError> {
         #[derive(CandidType, Deserialize)]
         struct In<TCycles> {
             canister: Principal,
@@ -103,29 +108,26 @@ where
                 canister: self.destination,
                 method_name: self.method_name,
                 args: self.arg.serialize()?,
-                cycles: u64::try_from(self.amount).map_err(|_| {
-                    AgentError::WalletUpgradeRequired(
-                        "The installed wallet does not support cycle counts >2^64-1".to_string(),
-                    )
-                })?,
+                cycles: u64::try_from(self.amount)
+                    .map_err(|_| WalletError::WalletUpgradeRequired(UpgradeReason::Cycles128))?,
             })
         }
         .build()
+        .map_err(WalletError::from)
         .and_then(|(result,): (Result<CallResult, String>,)| async move {
-            let result = result.map_err(AgentError::WalletCallFailed)?;
-            decode_args::<Out>(result.r#return.as_slice())
-                .map_err(|e| AgentError::CandidError(Box::new(e)))
+            let result = result.map_err(WalletError::WalletCallFailed)?;
+            decode_args::<Out>(result.r#return.as_slice()).map_err(WalletError::Candid)
         }))
     }
 
     /// Calls the forwarded canister call on the wallet canister. Equivalent to `.build().call()`.
-    pub fn call(self) -> impl Future<Output = Result<CallResponse<Out>, AgentError>> + 'agent {
+    pub fn call(self) -> impl Future<Output = Result<CallResponse<Out>, WalletError>> + 'agent {
         let call = self.build();
         async { call?.call().await }
     }
 
     /// Calls the forwarded canister call on the wallet canister, and waits for the result. Equivalent to `.build().call_and_wait()`.
-    pub fn call_and_wait(self) -> impl Future<Output = Result<Out, AgentError>> + 'agent {
+    pub fn call_and_wait(self) -> impl Future<Output = Result<Out, WalletError>> + 'agent {
         let call = self.build();
         async { call?.call_and_wait().await }
     }
@@ -138,12 +140,13 @@ where
     Out: for<'de> ArgumentDecoder<'de> + Send + Sync + 'agent,
 {
     type Value = Out;
+    type Error = WalletError;
 
-    async fn call(self) -> Result<CallResponse<Out>, AgentError> {
+    async fn call(self) -> Result<CallResponse<Out>, WalletError> {
         self.call().await
     }
 
-    async fn call_and_wait(self) -> Result<Out, AgentError> {
+    async fn call_and_wait(self) -> Result<Out, WalletError> {
         self.call_and_wait().await
     }
 }
@@ -152,8 +155,8 @@ impl<'agent: 'canister, 'canister, Out> IntoFuture for CallForwarder<'agent, 'ca
 where
     Out: for<'de> ArgumentDecoder<'de> + Send + Sync + 'agent,
 {
-    type IntoFuture = CallFuture<'agent, Out>;
-    type Output = Result<Out, AgentError>;
+    type IntoFuture = CallFuture<'agent, Out, WalletError>;
+    type Output = Result<Out, WalletError>;
     fn into_future(self) -> Self::IntoFuture {
         Box::pin(self.call_and_wait())
     }
@@ -433,7 +436,7 @@ impl<'agent> WalletCanister<'agent> {
     pub async fn create(
         agent: &'agent Agent,
         canister_id: Principal,
-    ) -> Result<WalletCanister<'agent>, AgentError> {
+    ) -> Result<WalletCanister<'agent>, WalletError> {
         let canister = Canister::builder()
             .with_agent(agent)
             .with_canister_id(canister_id)
@@ -445,20 +448,21 @@ impl<'agent> WalletCanister<'agent> {
     /// Create a `WalletCanister` interface from an existing canister object. Fails if it cannot learn the wallet's version.
     pub async fn from_canister(
         canister: Canister<'agent>,
-    ) -> Result<WalletCanister<'agent>, AgentError> {
+    ) -> Result<WalletCanister<'agent>, WalletError> {
         static DEFAULT_VERSION: Lazy<Version> = Lazy::new(|| Version::parse("0.1.0").unwrap());
         let version: Result<(String,), _> =
             canister.query("wallet_api_version").build().call().await;
         let version = match version {
-            Err(AgentError::UncertifiedReject {
-                reject: replica_error,
-                ..
-            }) if replica_error
-                .reject_message
-                .contains(REPLICA_ERROR_NO_SUCH_QUERY_METHOD)
-                || replica_error
-                    .reject_message
-                    .contains(IC_REF_ERROR_NO_SUCH_QUERY_METHOD) =>
+            Err(BaseError::Agent(err))
+                if err.kind() == ErrorKind::Reject
+                    && err.operation_info().is_some_and(|op| {
+                        matches!(&op.response, Some(Err(replica_error)) if replica_error
+                            .reject_message
+                            .contains(REPLICA_ERROR_NO_SUCH_QUERY_METHOD)
+                        || replica_error
+                            .reject_message
+                            .contains(IC_REF_ERROR_NO_SUCH_QUERY_METHOD))
+                    }) =>
             {
                 DEFAULT_VERSION.clone()
             }
@@ -477,8 +481,10 @@ impl<'agent> WalletCanister<'agent> {
 
 impl<'agent> WalletCanister<'agent> {
     /// Re-fetch the API version string of the wallet.
-    pub fn fetch_wallet_api_version(&self) -> impl 'agent + SyncCall<Value = (Option<String>,)> {
-        self.query("wallet_api_version").build()
+    pub fn fetch_wallet_api_version(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (Option<String>,), Error = WalletError> {
+        self.query_("wallet_api_version").build()
     }
 
     /// Get the (cached) API version of the wallet.
@@ -487,57 +493,82 @@ impl<'agent> WalletCanister<'agent> {
     }
 
     /// Get the friendly name of the wallet (if one exists).
-    pub fn name(&self) -> impl 'agent + SyncCall<Value = (Option<String>,)> {
-        self.query("name").build()
+    pub fn name(&self) -> impl 'agent + SyncCall<Value = (Option<String>,), Error = WalletError> {
+        self.query_("name").build()
     }
 
     /// Set the friendly name of the wallet.
-    pub fn set_name(&self, name: String) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("set_name").with_arg(name).build()
+    pub fn set_name(
+        &self,
+        name: String,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("set_name").with_arg(name).build()
     }
 
     /// Get the current controller's principal ID.
-    pub fn get_controllers(&self) -> impl 'agent + SyncCall<Value = (Vec<Principal>,)> {
-        self.query("get_controllers").build()
+    pub fn get_controllers(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (Vec<Principal>,), Error = WalletError> {
+        self.query_("get_controllers").build()
     }
 
     /// Transfer controller to another principal ID.
-    pub fn add_controller(&self, principal: Principal) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("add_controller").with_arg(principal).build()
+    pub fn add_controller(
+        &self,
+        principal: Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("add_controller").with_arg(principal).build()
     }
 
     /// Remove a user as a wallet controller.
-    pub fn remove_controller(&self, principal: Principal) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("remove_controller").with_arg(principal).build()
+    pub fn remove_controller(
+        &self,
+        principal: Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("remove_controller")
+            .with_arg(principal)
+            .build()
     }
 
     /// Get the list of custodians.
-    pub fn get_custodians(&self) -> impl 'agent + SyncCall<Value = (Vec<Principal>,)> {
-        self.query("get_custodians").build()
+    pub fn get_custodians(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (Vec<Principal>,), Error = WalletError> {
+        self.query_("get_custodians").build()
     }
 
     /// Authorize a new custodian.
-    pub fn authorize(&self, custodian: Principal) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("authorize").with_arg(custodian).build()
+    pub fn authorize(
+        &self,
+        custodian: Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("authorize").with_arg(custodian).build()
     }
 
     /// Deauthorize a custodian.
-    pub fn deauthorize(&self, custodian: Principal) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("deauthorize").with_arg(custodian).build()
+    pub fn deauthorize(
+        &self,
+        custodian: Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("deauthorize").with_arg(custodian).build()
     }
 
     /// Get the balance with the 64-bit API.
-    pub fn wallet_balance64(&self) -> impl 'agent + SyncCall<Value = (BalanceResult<u64>,)> {
-        self.query("wallet_balance").build()
+    pub fn wallet_balance64(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (BalanceResult<u64>,), Error = WalletError> {
+        self.query_("wallet_balance").build()
     }
 
     /// Get the balance with the 128-bit API.
-    pub fn wallet_balance128(&self) -> impl 'agent + SyncCall<Value = (BalanceResult,)> {
-        self.query("wallet_balance128").build()
+    pub fn wallet_balance128(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (BalanceResult,), Error = WalletError> {
+        self.query_("wallet_balance128").build()
     }
 
     /// Get the balance.
-    pub async fn wallet_balance(&self) -> Result<BalanceResult, AgentError> {
+    pub async fn wallet_balance(&self) -> Result<BalanceResult, WalletError> {
         if self.version_supports_u128_cycles() {
             self.wallet_balance128().call().await.map(|(r,)| r)
         } else {
@@ -555,14 +586,14 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         destination: Principal,
         amount: u64,
-    ) -> impl 'agent + AsyncCall<Value = (Result<(), String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<(), String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             canister: Principal,
             amount: u64,
         }
 
-        self.update("wallet_send")
+        self.update_("wallet_send")
             .with_arg(In {
                 canister: destination,
                 amount,
@@ -575,14 +606,14 @@ impl<'agent> WalletCanister<'agent> {
         &'canister self,
         destination: Principal,
         amount: u128,
-    ) -> impl 'agent + AsyncCall<Value = (Result<(), String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<(), String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             canister: Principal,
             amount: u128,
         }
 
-        self.update("wallet_send128")
+        self.update_("wallet_send128")
             .with_arg(In {
                 canister: destination,
                 amount,
@@ -595,32 +626,32 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         destination: Principal,
         amount: u128,
-    ) -> Result<(), AgentError> {
+    ) -> Result<(), WalletError> {
         if self.version_supports_u128_cycles() {
             self.wallet_send128(destination, amount)
                 .call_and_wait()
                 .await?
         } else {
-            let amount = u64::try_from(amount).map_err(|_| {
-                AgentError::WalletUpgradeRequired(
-                    "The installed wallet does not support cycle counts >2^64-1.".to_string(),
-                )
-            })?;
+            let amount = u64::try_from(amount)
+                .map_err(|_| WalletError::WalletUpgradeRequired(UpgradeReason::Cycles128))?;
             self.wallet_send64(destination, amount)
                 .call_and_wait()
                 .await?
         }
         .0
-        .map_err(AgentError::WalletError)
+        .map_err(WalletError::WalletError)
     }
 
     /// A function for sending cycles to, so that a memo can be passed along with them.
-    pub fn wallet_receive(&self, memo: Option<String>) -> impl 'agent + AsyncCall<Value = ((),)> {
+    pub fn wallet_receive(
+        &self,
+        memo: Option<String>,
+    ) -> impl 'agent + AsyncCall<Value = ((),), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             memo: Option<String>,
         }
-        self.update("wallet_receive")
+        self.update_("wallet_receive")
             .with_arg(memo.map(|memo| In { memo: Some(memo) }))
             .build()
     }
@@ -633,7 +664,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u64,
@@ -647,7 +678,7 @@ impl<'agent> WalletCanister<'agent> {
             freezing_threshold: freezing_threshold.map(u64::from).map(Nat::from),
         };
 
-        self.update("wallet_create_canister")
+        self.update_("wallet_create_canister")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -661,7 +692,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u64,
@@ -679,7 +710,7 @@ impl<'agent> WalletCanister<'agent> {
             log_visibility: None,
         };
 
-        self.update("wallet_create_canister")
+        self.update_("wallet_create_canister")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -693,7 +724,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u128,
@@ -711,7 +742,7 @@ impl<'agent> WalletCanister<'agent> {
             log_visibility: None,
         };
 
-        self.update("wallet_create_canister128")
+        self.update_("wallet_create_canister128")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -733,7 +764,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> Result<CreateResult, AgentError> {
+    ) -> Result<CreateResult, WalletError> {
         if self.version_supports_u128_cycles() {
             self.wallet_create_canister128(
                 cycles,
@@ -745,11 +776,8 @@ impl<'agent> WalletCanister<'agent> {
             .call_and_wait()
             .await?
         } else {
-            let cycles = u64::try_from(cycles).map_err(|_| {
-                AgentError::WalletUpgradeRequired(
-                    "The installed wallet does not support cycle counts >2^64-1.".to_string(),
-                )
-            })?;
+            let cycles = u64::try_from(cycles)
+                .map_err(|_| WalletError::WalletUpgradeRequired(UpgradeReason::Cycles128))?;
             if self.version_supports_multiple_controllers() {
                 self.wallet_create_canister64_v2(
                     cycles,
@@ -767,8 +795,8 @@ impl<'agent> WalletCanister<'agent> {
                         let first: Principal = *first.unwrap();
                         Ok(Some(first))
                     }
-                    Some(_) => Err(AgentError::WalletUpgradeRequired(
-                        "The installed wallet does not support multiple controllers.".to_string(),
+                    Some(_) => Err(WalletError::WalletUpgradeRequired(
+                        UpgradeReason::MultiController,
                     )),
                     None => Ok(None),
                 }?;
@@ -784,7 +812,7 @@ impl<'agent> WalletCanister<'agent> {
             }
         }
         .0
-        .map_err(AgentError::WalletError)
+        .map_err(WalletError::WalletError)
     }
 
     /// Create a wallet canister with the single-controller 64-bit API.
@@ -795,7 +823,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u64,
@@ -809,7 +837,7 @@ impl<'agent> WalletCanister<'agent> {
             freezing_threshold: freezing_threshold.map(u64::from).map(Nat::from),
         };
 
-        self.update("wallet_create_wallet")
+        self.update_("wallet_create_wallet")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -823,7 +851,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u64,
@@ -841,7 +869,7 @@ impl<'agent> WalletCanister<'agent> {
             log_visibility: None,
         };
 
-        self.update("wallet_create_wallet")
+        self.update_("wallet_create_wallet")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -855,7 +883,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,)> {
+    ) -> impl 'agent + AsyncCall<Value = (Result<CreateResult, String>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             cycles: u128,
@@ -873,7 +901,7 @@ impl<'agent> WalletCanister<'agent> {
             log_visibility: None,
         };
 
-        self.update("wallet_create_wallet128")
+        self.update_("wallet_create_wallet128")
             .with_arg(In { cycles, settings })
             .build()
             .map(|result: (Result<CreateResult, String>,)| (result.0,))
@@ -887,7 +915,7 @@ impl<'agent> WalletCanister<'agent> {
         compute_allocation: Option<ComputeAllocation>,
         memory_allocation: Option<MemoryAllocation>,
         freezing_threshold: Option<FreezingThreshold>,
-    ) -> Result<CreateResult, AgentError> {
+    ) -> Result<CreateResult, WalletError> {
         if self.version_supports_u128_cycles() {
             self.wallet_create_wallet128(
                 cycles,
@@ -899,11 +927,8 @@ impl<'agent> WalletCanister<'agent> {
             .call_and_wait()
             .await?
         } else {
-            let cycles = u64::try_from(cycles).map_err(|_| {
-                AgentError::WalletUpgradeRequired(
-                    "The installed wallet does not support cycle counts >2^64-1.".to_string(),
-                )
-            })?;
+            let cycles = u64::try_from(cycles)
+                .map_err(|_| WalletError::WalletUpgradeRequired(UpgradeReason::Cycles128))?;
             if self.version_supports_multiple_controllers() {
                 self.wallet_create_wallet64_v2(
                     cycles,
@@ -917,8 +942,8 @@ impl<'agent> WalletCanister<'agent> {
             } else {
                 let controller: Option<Principal> = match &controllers {
                     Some(c) if c.len() == 1 => Ok(Some(c[0])),
-                    Some(_) => Err(AgentError::WalletUpgradeRequired(
-                        "The installed wallet does not support multiple controllers.".to_string(),
+                    Some(_) => Err(WalletError::WalletUpgradeRequired(
+                        UpgradeReason::MultiController,
                     )),
                     None => Ok(None),
                 }?;
@@ -934,7 +959,7 @@ impl<'agent> WalletCanister<'agent> {
             }
         }
         .0
-        .map_err(AgentError::WalletError)
+        .map_err(WalletError::WalletError)
     }
 
     /// Store the wallet WASM inside the wallet canister.
@@ -942,30 +967,38 @@ impl<'agent> WalletCanister<'agent> {
     pub fn wallet_store_wallet_wasm(
         &self,
         wasm_module: Vec<u8>,
-    ) -> impl 'agent + AsyncCall<Value = ()> {
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
         #[derive(CandidType, Deserialize)]
         struct In {
             #[serde(with = "serde_bytes")]
             wasm_module: Vec<u8>,
         }
-        self.update("wallet_store_wallet_wasm")
+        self.update_("wallet_store_wallet_wasm")
             .with_arg(In { wasm_module })
             .build()
     }
 
     /// Add a principal to the address book.
-    pub fn add_address(&self, address: AddressEntry) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("add_address").with_arg(address).build()
+    pub fn add_address(
+        &self,
+        address: AddressEntry,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("add_address").with_arg(address).build()
     }
 
     /// List the entries in the address book.
-    pub fn list_addresses(&self) -> impl 'agent + SyncCall<Value = (Vec<AddressEntry>,)> {
-        self.query("list_addresses").build()
+    pub fn list_addresses(
+        &self,
+    ) -> impl 'agent + SyncCall<Value = (Vec<AddressEntry>,), Error = WalletError> {
+        self.query_("list_addresses").build()
     }
 
     /// Remove a principal from the address book.
-    pub fn remove_address(&self, principal: Principal) -> impl 'agent + AsyncCall<Value = ()> {
-        self.update("remove_address").with_arg(principal).build()
+    pub fn remove_address(
+        &self,
+        principal: Principal,
+    ) -> impl 'agent + AsyncCall<Value = (), Error = WalletError> {
+        self.update_("remove_address").with_arg(principal).build()
     }
 
     /// Get a list of all transaction events this wallet remembers, using the 64-bit API. Fails if any events are 128-bit.
@@ -973,7 +1006,7 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (Vec<Event<u64>>,)> {
+    ) -> impl 'agent + SyncCall<Value = (Vec<Event<u64>>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             from: Option<u32>,
@@ -986,7 +1019,7 @@ impl<'agent> WalletCanister<'agent> {
             Some(In { from, to })
         };
 
-        self.query("get_events").with_arg(arg).build()
+        self.query_("get_events").with_arg(arg).build()
     }
 
     /// Get a list of all transaction events this wallet remembers, using the 128-bit API.
@@ -994,7 +1027,7 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (Vec<Event>,)> {
+    ) -> impl 'agent + SyncCall<Value = (Vec<Event>,), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             from: Option<u32>,
@@ -1005,7 +1038,7 @@ impl<'agent> WalletCanister<'agent> {
         } else {
             Some(In { from, to })
         };
-        self.query("get_events128").with_arg(arg).build()
+        self.query_("get_events128").with_arg(arg).build()
     }
 
     /// Get a list of all transaction events this wallet remembers.
@@ -1013,7 +1046,7 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> Result<Vec<Event>, AgentError> {
+    ) -> Result<Vec<Event>, WalletError> {
         if self.version_supports_u128_cycles() {
             self.get_events128(from, to)
                 .call()
@@ -1101,13 +1134,13 @@ impl<'agent> WalletCanister<'agent> {
         &self,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (Vec<ManagedCanisterInfo>, u32)> {
+    ) -> impl 'agent + SyncCall<Value = (Vec<ManagedCanisterInfo>, u32), Error = WalletError> {
         #[derive(CandidType)]
         struct In {
             from: Option<u32>,
             to: Option<u32>,
         }
-        self.query("list_managed_canisters")
+        self.query_("list_managed_canisters")
             .with_arg((In { from, to },))
             .build()
     }
@@ -1118,14 +1151,15 @@ impl<'agent> WalletCanister<'agent> {
         canister: Principal,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (Option<Vec<ManagedCanisterEvent<u64>>>,)> {
+    ) -> impl 'agent + SyncCall<Value = (Option<Vec<ManagedCanisterEvent<u64>>>,), Error = WalletError>
+    {
         #[derive(CandidType)]
         struct In {
             canister: Principal,
             from: Option<u32>,
             to: Option<u32>,
         }
-        self.query("get_managed_canister_events")
+        self.query_("get_managed_canister_events")
             .with_arg((In { canister, from, to },))
             .build()
     }
@@ -1136,14 +1170,15 @@ impl<'agent> WalletCanister<'agent> {
         canister: Principal,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> impl 'agent + SyncCall<Value = (Option<Vec<ManagedCanisterEvent>>,)> {
+    ) -> impl 'agent + SyncCall<Value = (Option<Vec<ManagedCanisterEvent>>,), Error = WalletError>
+    {
         #[derive(CandidType)]
         struct In {
             canister: Principal,
             from: Option<u32>,
             to: Option<u32>,
         }
-        self.query("get_managed_canister_events128")
+        self.query_("get_managed_canister_events128")
             .with_arg((In { canister, from, to },))
             .build()
     }
@@ -1154,7 +1189,7 @@ impl<'agent> WalletCanister<'agent> {
         canister: Principal,
         from: Option<u32>,
         to: Option<u32>,
-    ) -> Result<Option<Vec<ManagedCanisterEvent>>, AgentError> {
+    ) -> Result<Option<Vec<ManagedCanisterEvent>>, WalletError> {
         if self.version_supports_u128_cycles() {
             self.get_managed_canister_events128(canister, from, to)
                 .call()
@@ -1183,3 +1218,47 @@ impl<'agent> WalletCanister<'agent> {
         U128_CYCLES.matches(&self.version)
     }
 }
+
+/// An error that can occur when interfacing with a wallet canister.
+#[derive(Error, Debug)]
+pub enum WalletError {
+    /// An error occurred encoding/decoding Candid.
+    #[error("{0}")]
+    Candid(#[from] candid::Error),
+    /// An error occurred in the agent.
+    #[error("{0}")]
+    Agent(#[from] AgentError),
+    /// The wallet canister must be upgraded.
+    #[error("The wallet canister must be upgraded: {0}")]
+    WalletUpgradeRequired(UpgradeReason),
+    /// The `call_forward` call failed.
+    #[error("The invocation to the wallet call forward method failed with the error: {0}")]
+    WalletCallFailed(String),
+    /// The wallet returned an error.
+    #[error("The wallet operation failed: {0}")]
+    WalletError(String),
+}
+
+impl_canister_error!(WalletError);
+
+/// The reason for [`WalletError::WalletUpgradeRequired`].
+#[derive(Debug, Eq, PartialEq)]
+pub enum UpgradeReason {
+    /// The wallet does not support a 128-bit cycle count.
+    Cycles128,
+    /// The wallet does not support multiple controllers.
+    MultiController,
+}
+
+impl Display for UpgradeReason {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Cycles128 => {
+                f.write_str("the installed wallet does not support cycle counts >2^64-1")
+            }
+            Self::MultiController => {
+                f.write_str("the installed wallet does not support multiple controllers")
+            }
+        }
+    }
+}
diff --git a/ic-utils/src/lib.rs b/ic-utils/src/lib.rs
index 2f7e70cc..3331e7f0 100644
--- a/ic-utils/src/lib.rs
+++ b/ic-utils/src/lib.rs
@@ -15,6 +15,8 @@
 pub mod call;
 /// A higher-level canister type for managing various aspects of a canister.
 pub mod canister;
+/// An error interface for canister errors.
+pub mod error;
 /// A few known canister types for use with [`Canister`].
 pub mod interfaces;
 
diff --git a/icx/src/main.rs b/icx/src/main.rs
index 02ca06e6..54034e4d 100644
--- a/icx/src/main.rs
+++ b/icx/src/main.rs
@@ -16,7 +16,7 @@ use ic_agent::{
     },
     export::Principal,
     identity::BasicIdentity,
-    Agent, AgentError, Identity,
+    Agent, Identity,
 };
 use ic_utils::interfaces::management_canister::{
     builders::{CanisterInstall, CanisterSettings},
@@ -453,9 +453,10 @@ async fn main() -> Result<()> {
                         let result = tokio::select!(
                             Ok(unreachable) = tokio::spawn(printer) => unreachable,
                             res = tokio::time::timeout(Duration::from_secs(5 * 60), result) => res,
-                        );
+                        )
+                        .context("timed out")?;
                         eprintln!();
-                        result.unwrap_or(Err(AgentError::TimeoutWaitingForResponse()))
+                        result
                     }
                     SubCommand::Query(_) => {
                         fetch_root_key_from_non_ic(&agent, &opts.replica).await?;
@@ -478,35 +479,38 @@ async fn main() -> Result<()> {
                         print_idl_blob(&blob, &t.output, &method_type)
                             .context("Failed to print result blob")?;
                     }
-                    Err(AgentError::TransportError(_)) => return Ok(()),
-                    Err(AgentError::HttpError(HttpErrorPayload {
-                        status,
-                        content_type,
-                        content,
-                    })) => {
-                        let mut error_message =
-                            format!("Server returned an HTTP Error:\n  Code: {status}\n");
-                        match content_type.as_deref() {
-                            None => error_message
-                                .push_str(&format!("  Content: {}\n", hex::encode(content))),
-                            Some("text/plain; charset=UTF-8" | "text/plain") => {
-                                error_message.push_str("  ContentType: text/plain\n");
-                                error_message.push_str(&format!(
-                                    "  Content:     {}\n",
-                                    String::from_utf8_lossy(&content)
-                                ));
-                            }
-                            Some(x) => {
-                                error_message.push_str(&format!("  ContentType: {x}\n"));
-                                error_message.push_str(&format!(
-                                    "  Content:     {}\n",
-                                    hex::encode(&content)
-                                ));
+                    Err(e) => {
+                        if let Some(HttpErrorPayload {
+                            content,
+                            content_type,
+                            status,
+                        }) = e.as_http_error()
+                        {
+                            let mut error_message =
+                                format!("Server returned an HTTP Error:\n  Code: {status}\n");
+                            match content_type.as_deref() {
+                                None => error_message
+                                    .push_str(&format!("  Content: {}\n", hex::encode(content))),
+                                Some("text/plain; charset=UTF-8" | "text/plain") => {
+                                    error_message.push_str("  ContentType: text/plain\n");
+                                    error_message.push_str(&format!(
+                                        "  Content:     {}\n",
+                                        String::from_utf8_lossy(content)
+                                    ));
+                                }
+                                Some(x) => {
+                                    error_message.push_str(&format!("  ContentType: {x}\n"));
+                                    error_message.push_str(&format!(
+                                        "  Content:     {}\n",
+                                        hex::encode(content)
+                                    ));
+                                }
                             }
+                            bail!(error_message);
+                        } else {
+                            return Err(e.into());
                         }
-                        bail!(error_message);
                     }
-                    Err(s) => Err(s).context("Got an error when make the canister call")?,
                 }
             }
         }
diff --git a/ref-tests/Cargo.toml b/ref-tests/Cargo.toml
index 07cc0629..17373f7e 100644
--- a/ref-tests/Cargo.toml
+++ b/ref-tests/Cargo.toml
@@ -9,6 +9,7 @@ publish = false
 [dependencies]
 candid = { workspace = true }
 ed25519-consensus = { workspace = true }
+hex.workspace = true
 ic-agent = { path = "../ic-agent" }
 ic-identity-hsm = { path = "../ic-identity-hsm" }
 ic-utils = { path = "../ic-utils", features = ["raw"] }
diff --git a/ref-tests/src/utils.rs b/ref-tests/src/utils.rs
index 254d4025..4ecea7bf 100644
--- a/ref-tests/src/utils.rs
+++ b/ref-tests/src/utils.rs
@@ -1,9 +1,14 @@
+use candid::IDLArgs;
 use ed25519_consensus::SigningKey;
+use ic_agent::agent::RejectResponse;
 use ic_agent::identity::{Prime256v1Identity, Secp256k1Identity};
+use ic_agent::AgentError;
 use ic_agent::{export::Principal, identity::BasicIdentity, Agent, Identity};
 use ic_identity_hsm::HardwareIdentity;
+use ic_utils::error::CanisterError;
 use ic_utils::interfaces::{management_canister::builders::MemoryAllocation, ManagementCanister};
 use rand::thread_rng;
+use std::fmt::Debug;
 use std::{convert::TryFrom, error::Error, future::Future, path::Path};
 
 const HSM_PKCS11_LIBRARY_PATH: &str = "HSM_PKCS11_LIBRARY_PATH";
@@ -243,3 +248,45 @@ where
         f(agent, canister_id).await
     })
 }
+
+#[track_caller]
+pub fn assert_reject2<T: Debug, E: CanisterError>(res: &Result<T, E>) -> &RejectResponse {
+    match res {
+        Ok(o) => panic!("expected Err, got Ok({o:?})"),
+        Err(e) => match e.as_agent() {
+            Some(err) => assert_reject_err(err),
+            None => panic!("expected agent error, got {e}"),
+        },
+    }
+}
+
+#[track_caller]
+pub fn assert_reject<T: Debug>(res: &Result<T, AgentError>) -> &RejectResponse {
+    match res {
+        Ok(o) => panic!("expected Err, got Ok({o:?})"),
+        Err(e) => assert_reject_err(e),
+    }
+}
+
+#[track_caller]
+pub fn assert_reject_err(e: &AgentError) -> &RejectResponse {
+    match e.operation_info() {
+        None => panic!("error did not come with operation info. error: {e}"),
+        Some(info) => match &info.response {
+            None => {
+                panic!("operation info did not come with response. info: {info:?}, error: {e}")
+            }
+            Some(resp) => match resp {
+                Ok(resp) => panic!(
+                    "expected error, got success: {}",
+                    if let Ok(val) = IDLArgs::from_bytes(resp) {
+                        format!("{val:?}")
+                    } else {
+                        hex::encode(resp)
+                    }
+                ),
+                Err(err) => err,
+            },
+        },
+    }
+}
diff --git a/ref-tests/tests/ic-ref.rs b/ref-tests/tests/ic-ref.rs
index 96e384cc..7fe5a1e1 100644
--- a/ref-tests/tests/ic-ref.rs
+++ b/ref-tests/tests/ic-ref.rs
@@ -27,10 +27,11 @@ mod management_canister {
     use ic_agent::{
         agent::{RejectCode, RejectResponse},
         export::Principal,
-        AgentError, Identity,
+        Identity,
     };
     use ic_utils::{
         call::AsyncCall,
+        error::CanisterError,
         interfaces::{
             management_canister::{
                 builders::{
@@ -43,23 +44,18 @@ mod management_canister {
         },
         Argument,
     };
-    use ref_tests::get_effective_canister_id;
+    use ref_tests::{assert_reject, assert_reject2, get_effective_canister_id};
     use ref_tests::{
         create_agent, create_basic_identity, create_prime256v1_identity, create_secp256k1_identity,
         with_agent, with_wallet_canister,
     };
     use sha2::{Digest, Sha256};
     use std::collections::HashSet;
-    use std::convert::TryInto;
+    use std::{convert::TryInto, fmt::Debug};
 
     mod create_canister {
         use super::with_agent;
-        use ic_agent::{
-            agent::{RejectCode, RejectResponse},
-            export::Principal,
-            AgentError,
-            AgentError::HttpError,
-        };
+        use ic_agent::export::Principal;
 
         use ic_utils::interfaces::ManagementCanister;
         use ref_tests::get_effective_canister_id;
@@ -98,15 +94,10 @@ mod management_canister {
                     .call_and_wait()
                     .await;
 
+                let msg = result.unwrap_err().to_string();
                 assert!(
-                    matches!(result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
-                    reject_code: RejectCode::DestinationInvalid,
-                    ref reject_message,
-                    error_code: Some(ref error_code)
-                }, .. }) if reject_message == "Canister 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q not found" &&
-                        error_code == "IC0301")
-                        || matches!(result, Err(HttpError(content)) if content.status == 400 && content.content == b"Canister 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q does not belong to any subnet.")
+                    msg.contains("Canister 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q does not belong to any subnet.")
+                    || msg.contains("Canister 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q not found")
                 );
 
                 Ok(())
@@ -142,7 +133,7 @@ mod management_canister {
                 .call_and_wait()
                 .await;
 
-            assert!(matches!(result, Err(AgentError::CertifiedReject { .. })));
+            assert_reject2(&result);
 
             // Reinstall should succeed.
             ic00.install_code(&canister_id, &canister_wasm)
@@ -163,7 +154,7 @@ mod management_canister {
                 .with_mode(InstallMode::Reinstall)
                 .call_and_wait()
                 .await;
-            assert!(matches!(result, Err(AgentError::UncertifiedReject { .. })));
+            assert_reject2(&result);
 
             // Upgrade should succeed.
             ic00.install_code(&canister_id, &canister_wasm)
@@ -183,7 +174,7 @@ mod management_canister {
                 })))
                 .call_and_wait()
                 .await;
-            assert!(matches!(result, Err(AgentError::UncertifiedReject { .. })));
+            assert_reject2(&result);
 
             // Change controller.
             ic00.update_settings(&canister_id)
@@ -197,14 +188,12 @@ mod management_canister {
                 .with_controller(other_agent_principal)
                 .call_and_wait()
                 .await;
-            assert!(
-                matches!(result, Err(AgentError::UncertifiedReject { reject: RejectResponse{
+            assert!(matches!(assert_reject2(&result), RejectResponse{
                 reject_code: RejectCode::CanisterError,
                 reject_message,
                 error_code: Some(ref error_code),
-            }, .. }) if reject_message == format!("Only controllers of canister {} can call ic00 method update_settings", canister_id) &&
-                    error_code == "IC0512")
-            );
+            } if *reject_message == format!("Only controllers of canister {} can call ic00 method update_settings", canister_id) &&
+                    error_code == "IC0512"));
 
             // Reinstall as new controller
             other_ic00
@@ -406,23 +395,25 @@ mod management_canister {
         })
     }
 
-    fn assert_err_or_reject<S>(
-        result: Result<S, AgentError>,
+    #[track_caller]
+    fn assert_err_or_reject<S: Debug, E: CanisterError>(
+        result: Result<S, E>,
         allowed_reject_codes: Vec<RejectCode>,
     ) {
-        for expected_rc in &allowed_reject_codes {
-            if matches!(result,
-                Err(AgentError::UncertifiedReject { reject: RejectResponse {
-                reject_code,
-                ..
-            }, .. }) if reject_code == *expected_rc)
-            {
-                return;
+        let error = result.unwrap_err();
+        let error = error.as_agent().unwrap();
+        if let Some(info) = error.operation_info() {
+            if let Some(Err(err)) = &info.response {
+                for expected_rc in &allowed_reject_codes {
+                    if err.reject_code == *expected_rc {
+                        return;
+                    }
+                }
             }
         }
 
         assert!(
-            matches!(result, Err(AgentError::HttpError(_))),
+            error.as_http_error().is_some(),
             "expect an HttpError, or a CertifiedReject with reject_code in {:?}",
             allowed_reject_codes
         );
@@ -465,12 +456,12 @@ mod management_canister {
             let result = agent.update(&canister_id, "update").call_and_wait().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Canister {canister_id} is stopped")
+                    } if *reject_message == format!("Canister {canister_id} is stopped")
                         && error_code == "IC0508"
                 ),
                 "wrong error: {result:?}"
@@ -480,12 +471,12 @@ mod management_canister {
             let result = agent.query(&canister_id, "query").with_arg([]).call().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("IC0508: Canister {canister_id} is stopped and therefore does not have a CallContextManager")
+                    } if reject_message.trim_start_matches("IC0508: ") == format!("Canister {canister_id} is stopped and therefore does not have a CallContextManager")
                         && error_code == "IC0508"
                 ),
                 "wrong error: {result:?}"
@@ -511,12 +502,12 @@ mod management_canister {
             let result = agent.update(&canister_id, "update").call_and_wait().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::CertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                     RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if reject_message.contains(&format!("Canister {canister_id}: Canister has no update method 'update'"))
+                    } if reject_message.contains(&format!("Canister {canister_id}: Canister has no update method 'update'"))
                         && error_code == "IC0536"
                 ),
                 "wrong error: {result:?}"
@@ -526,12 +517,12 @@ mod management_canister {
             let result = agent.query(&canister_id, "query").with_arg([]).call().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if reject_message.contains(&format!("Canister {}: Canister has no query method 'query'", canister_id))
+                    } if reject_message.contains(&format!("Canister {}: Canister has no query method 'query'", canister_id))
                         && error_code == "IC0536",
                 ),
                 "wrong error: {result:?}"
@@ -550,12 +541,12 @@ mod management_canister {
             let result = agent.update(&canister_id, "update").call_and_wait().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                     RejectResponse {
                         reject_code: RejectCode::DestinationInvalid,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Canister {} not found", canister_id)
+                    } if *reject_message == format!("Canister {} not found", canister_id)
                         && error_code == "IC0301"
                 ),
                 "wrong error: {result:?}"
@@ -565,12 +556,12 @@ mod management_canister {
             let result = agent.query(&canister_id, "query").with_arg([]).call().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject(&result),
+                    RejectResponse {
                         reject_code: RejectCode::DestinationInvalid,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("IC0301: Canister {} not found", canister_id)
+                    } if reject_message.trim_start_matches("IC0301: ") == format!("Canister {} not found", canister_id)
                         && error_code == "IC0301"
                 ),
                 "wrong error: {result:?}"
@@ -579,23 +570,15 @@ mod management_canister {
             // Cannot query canister status
             let result = ic00.canister_status(&canister_id).call_and_wait().await;
             assert!(
-                match &result {
-                    Err(AgentError::UncertifiedReject {
-                        reject:
-                            RejectResponse {
-                                reject_code: RejectCode::DestinationInvalid,
-                                reject_message,
-                                error_code: Some(error_code),
-                            },
-                        ..
-                    }) if *reject_message == format!("Canister {} not found", canister_id)
-                        && error_code == "IC0301" =>
-                    {
-                        true
-                    }
-                    Ok((_status_call_result,)) => false,
-                    _ => false,
-                },
+                matches!(
+                    assert_reject2(&result),
+                    RejectResponse {
+                        reject_code: RejectCode::DestinationInvalid,
+                        reject_message,
+                        error_code: Some(error_code),
+                    } if *reject_message == format!("Canister {} not found", canister_id)
+                        && error_code == "IC0301"
+                ),
                 "wrong error: {result:?}"
             );
 
@@ -603,12 +586,12 @@ mod management_canister {
             let result = ic00.delete_canister(&canister_id).call_and_wait().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse{
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::DestinationInvalid,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Canister {} not found", canister_id)
+                    } if *reject_message == format!("Canister {} not found", canister_id)
                         && error_code == "IC0301"
                 ),
                 "wrong error: {result:?}"
@@ -649,12 +632,12 @@ mod management_canister {
                 .await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Only controllers of canister {} can call ic00 method start_canister", canister_id)
+                    } if *reject_message == format!("Only controllers of canister {} can call ic00 method start_canister", canister_id)
                         && error_code == "IC0512"
                 ),
                 "wrong error: {result:?}"
@@ -664,12 +647,12 @@ mod management_canister {
             let result = other_ic00.stop_canister(&canister_id).call_and_wait().await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, ..}) if *reject_message == format!("Only controllers of canister {} can call ic00 method stop_canister", canister_id)
+                    } if *reject_message == format!("Only controllers of canister {} can call ic00 method stop_canister", canister_id)
                         && error_code == "IC0512"
                 ),
                 "wrong error: {result:?}"
@@ -682,12 +665,12 @@ mod management_canister {
                 .await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Only controllers of canister {canister_id} can call ic00 method canister_status")
+                    } if *reject_message == format!("Only controllers of canister {canister_id} can call ic00 method canister_status")
                         && error_code == "IC0512"
                 ),
                 "wrong error: {result:?}"
@@ -700,12 +683,12 @@ mod management_canister {
                 .await;
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject { reject: RejectResponse {
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(error_code),
-                    }, .. }) if *reject_message == format!("Only controllers of canister {canister_id} can call ic00 method delete_canister")
+                    } if *reject_message == format!("Only controllers of canister {canister_id} can call ic00 method delete_canister")
                         && error_code == "IC0512"
                 ),
                 "wrong error: {result:?}"
@@ -844,7 +827,6 @@ mod management_canister {
                 )
                 .call_and_wait()
                 .await?;
-
             assert_eq!(rand_1.len(), 32);
             assert_eq!(rand_2.len(), 32);
             assert_eq!(rand_3.len(), 32);
@@ -928,11 +910,8 @@ mod management_canister {
 
 mod simple_calls {
     use crate::universal_canister::payload;
-    use ic_agent::{
-        agent::{RejectCode, RejectResponse},
-        AgentError,
-    };
-    use ref_tests::with_universal_canister;
+    use ic_agent::agent::{RejectCode, RejectResponse};
+    use ref_tests::{assert_reject, with_universal_canister};
 
     #[ignore]
     #[test]
@@ -988,14 +967,11 @@ mod simple_calls {
 
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::CertifiedReject {
-                        reject: RejectResponse {
-                            reject_code: RejectCode::CanisterError,
-                            ..
-                        },
+                    assert_reject(&result),
+                    RejectResponse {
+                        reject_code: RejectCode::CanisterError,
                         ..
-                    }),
+                    },
                 ),
                 "wrong error: {result:?}"
             );
@@ -1016,14 +992,11 @@ mod simple_calls {
 
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::UncertifiedReject {
-                        reject: RejectResponse {
-                            reject_code: RejectCode::CanisterError,
-                            ..
-                        },
+                    assert_reject(&result),
+                    RejectResponse {
+                        reject_code: RejectCode::CanisterError,
                         ..
-                    })
+                    },
                 ),
                 "wrong error: {result:?}"
             );
@@ -1037,7 +1010,6 @@ mod extras {
     use ic_agent::{
         agent::{RejectCode, RejectResponse},
         export::Principal,
-        AgentError,
     };
     use ic_utils::{
         call::AsyncCall,
@@ -1046,7 +1018,7 @@ mod extras {
             ManagementCanister,
         },
     };
-    use ref_tests::{get_effective_canister_id, with_agent};
+    use ref_tests::{assert_reject2, get_effective_canister_id, with_agent};
 
     #[ignore]
     #[test]
@@ -1255,12 +1227,12 @@ mod extras {
 
             assert!(
                 matches!(
-                    &result,
-                    Err(AgentError::CertifiedReject { reject: RejectResponse {
+                    assert_reject2(&result),
+                    RejectResponse {
                         reject_code: RejectCode::CanisterError,
                         reject_message,
                         error_code: Some(code),
-                    }, .. }) if reject_message.contains("Canister iimsn-6yaaa-aaaaa-afiaa-cai is already installed") && code == "IC0538"
+                    } if reject_message.contains("Canister iimsn-6yaaa-aaaaa-afiaa-cai is already installed") && code == "IC0538"
                 ),
                 "wrong error: {result:?}"
             );
diff --git a/ref-tests/tests/integration.rs b/ref-tests/tests/integration.rs
index 2a5681eb..1b2a36f4 100644
--- a/ref-tests/tests/integration.rs
+++ b/ref-tests/tests/integration.rs
@@ -6,13 +6,14 @@ use candid::CandidType;
 use ic_agent::{
     agent::{agent_error::HttpErrorPayload, Envelope, EnvelopeContent, RejectCode, RejectResponse},
     export::Principal,
-    AgentError, Identity,
+    Identity,
 };
 use ic_certification::Label;
 use ic_utils::{
     call::{AsyncCall, SyncCall},
     interfaces::{
         management_canister::builders::{CanisterSettings, InstallMode},
+        wallet::WalletError,
         WalletCanister,
     },
     Argument, Canister,
@@ -25,6 +26,7 @@ use ref_tests::{
 use serde::Serialize;
 use std::{
     borrow::Cow,
+    error::Error,
     sync::Arc,
     time::{Duration, SystemTime, UNIX_EPOCH},
 };
@@ -53,10 +55,13 @@ fn basic_expiry() {
             .call_and_wait()
             .await;
 
-        match result.unwrap_err() {
-            AgentError::HttpError(HttpErrorPayload { status, .. }) => assert_eq!(status, 400),
-            x => panic!("Was expecting an error, got {:?}", x),
-        }
+        let err = result.unwrap_err();
+        let payload = err
+            .source()
+            .unwrap()
+            .downcast_ref::<HttpErrorPayload>()
+            .unwrap();
+        assert_eq!(payload.status, 400);
 
         let result = agent
             .update(&canister_id, "update")
@@ -184,21 +189,23 @@ fn canister_reject_call() {
             WalletCanister::create(&agent, create_wallet_canister(&agent, None).await?).await?;
 
         let result = alice.wallet_send(*bob.canister_id(), 1_000_000).await;
-
+        let WalletError::Agent(err) = result.unwrap_err() else {
+            panic!("not an agent error")
+        };
         assert!(
             matches!(
-                &result,
-                Err(AgentError::CertifiedReject { reject: RejectResponse {
+                &err.operation_info().unwrap().response,
+                Some(Err(RejectResponse {
                     reject_code: RejectCode::CanisterError,
                     reject_message,
                     error_code: Some(error_code),
                     ..
-                }, .. }) if reject_message.contains(&format!(
+                })) if reject_message.contains(&format!(
                     "Canister {}: Canister has no update method 'wallet_send'",
                     alice.canister_id()
                 )) && error_code == "IC0536"
             ),
-            "wrong error: {result:?}"
+            "wrong error: {err:?}"
         );
 
         Ok(())
@@ -211,11 +218,18 @@ fn read_state_canister() {
     with_universal_canister(|agent, canister_id| async move {
         let blob = agent
             .read_state_canister_info(canister_id, "module_hash")
-            .await?;
+            .await?
+            .unwrap();
         assert_eq!(blob.len(), 32);
-        let controllers = agent.read_state_canister_controllers(canister_id).await?;
+        let controllers = agent
+            .read_state_canister_controllers(canister_id)
+            .await?
+            .unwrap();
         assert_eq!(controllers.len(), 1);
-        let hash = agent.read_state_canister_module_hash(canister_id).await?;
+        let hash = agent
+            .read_state_canister_module_hash(canister_id)
+            .await?
+            .unwrap();
         assert_eq!(hash.len(), 32);
         Ok(())
     })
@@ -572,7 +586,7 @@ mod sign_send {
             signed_query_inspect, signed_request_status_inspect, signed_update_inspect,
             ReplyResponse, RequestStatusResponse,
         },
-        AgentError,
+        agent_error::InspectionError,
     };
     use ref_tests::{universal_canister::payload, with_universal_canister};
     use std::{thread, time};
@@ -680,7 +694,7 @@ mod sign_send {
             );
 
             assert!(matches!(result,
-                    Err(AgentError::CallDataMismatch{field, value_arg, value_cbor})
+                    Err(InspectionError::CallDataMismatch{field, value_arg, value_cbor})
                     if field == *"method_name" && value_arg == *"non_query" && value_cbor == *"query"));
 
             Ok(())