Enum ClientError 

#[non_exhaustive]
pub enum ClientError {
    Http(Error),
    HttpClient(String),
    Serialization(Error),
    Protocol(A2aError),
    Transport(String),
    InvalidEndpoint(String),
    UnexpectedStatus {
        status: u16,
        body: String,
        retry_after: Option<Duration>,
    },
    AuthRequired {
        task_id: TaskId,
    },
    Timeout(String),
    TooManyPendingRequests {
        limit: usize,
    },
    IncompleteStream {
        last_event_id: Option<String>,
        detail: String,
    },
    ProtocolBindingMismatch(String),
}

Errors that can occur during A2A client operations.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Http(Error)

A transport-level HTTP error from hyper.

HttpClient(String)

An HTTP-level error from the hyper-util client (connection, redirect, etc.).

Serialization(Error)

JSON serialization or deserialization error.

Protocol(A2aError)

A protocol-level A2A error returned by the server.

Transport(String)

A transport configuration or connection error.

InvalidEndpoint(String)

The agent endpoint URL is invalid or could not be resolved.

UnexpectedStatus

The server returned an unexpected HTTP status code.

Fields

status: u16

The HTTP status code received.

body: String

The response body (truncated if large).

retry_after: Option<Duration>

Server-requested retry delay parsed from a Retry-After header (delta-seconds), when present on a 429/503. The retry layer honors this in preference to its own computed backoff so the client does not hammer a server that explicitly asked it to wait.

AuthRequired

The agent requires authentication for this task.

Fields

task_id: TaskId

The ID of the task requiring authentication.

Timeout(String)

A request or stream connection timed out.

TooManyPendingRequests

The connection already has limit requests awaiting responses, and this one was refused up front rather than queued. Retryable: room appears as responses arrive. See WebSocketTransportConfig::max_pending_requests.

Fields

limit: usize

The configured cap that was hit.

IncompleteStream

A stream ended before the event that finishes it.

A stream finishes cleanly on a Message, or on a Task or status update whose state is terminal (completed, failed, canceled, rejected) or interrupted (input-required, auth-required) — the states at which the specification says the server closes it (§3.1.2, §11.7). A body that ends, or a connection that closes, anywhere else is this error rather than a quiet None: the task is very likely still running, and the consumer is missing the rest of it.

Retryable in the sense that matters for a stream: resubscribe with A2aClient::subscribe_to_task_from, passing last_event_id, and a server that keeps an event log replays what was missed.

Fields

last_event_id: Option<String>

The last SSE id: received before the stream ended — the value to resume from. None when the server sent none: gRPC and WebSocket streams carry no ids, and neither does a server without resumption.

detail: String

What was missing, for the message.

ProtocolBindingMismatch(String)

The server appears to use a different protocol binding than the client.

For example, a JSON-RPC client connected to a REST-only server (or vice-versa). Check the agent card’s supported_interfaces to select the correct protocol binding.

Implementations

impl ClientError

pub const fn retry_after(&self) -> Option<Duration>

Server-requested retry delay, if this error carries one (a Retry-After header on a 429/503). The retry layer prefers this over its computed backoff.

pub fn is_stream_lagged(&self) -> bool

Returns true when this is the consumer-lag signal on a streaming subscription: the reader fell too far behind the agent, and the stream was cut off, rather than the task failing.

The stream ends here; the task does not. This SDK’s server writes one lag error frame when a reader overruns its event queue and then closes the stream, and the WebSocket transport ends a stream the same way once 64 frames are waiting unread (audit N29). What was read is a contiguous prefix. To continue, resubscribe: over SSE with subscribe_to_task_from and the stream’s last event id, which replays what was missed.

while let Some(event) = stream.next().await {
    match event {
        Ok(ev) => { /* handle */ }
        // Not a task failure: the stream was cut off. Resubscribe.
        Err(e) if e.is_stream_lagged() => {
            eprintln!("stream cut off after {:?} dropped events", e.dropped_event_count());
            break;
        }
        Err(e) => break, // a real failure
    }
}

pub fn dropped_event_count(&self) -> Option<u64>

Number of events the server dropped, when this is a consumer-lag signal (see ClientError::is_stream_lagged); None otherwise.

impl ClientError

pub const fn is_retryable(&self) -> bool

Returns true if this error is transient and the request should be retried.

Retryable errors include:

• HTTP connection/transport errors
• Timeouts
• Server errors (HTTP 502, 503, 504, 429)
• The client’s own in-flight cap (TooManyPendingRequests), which clears as responses arrive
• A stream that ended before its final event (IncompleteStream), which a resubscribe resumes

Trait Implementations

impl Debug for ClientError

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

Formats the value using the given formatter.

impl Display for ClientError

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

Formats the value using the given formatter.

impl Error for ClientError

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

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

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

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

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

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

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

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

impl From<A2aError> for ClientError

fn from(e: A2aError) -> ClientError

Converts to this type from the input type.

impl From<ClientError> for A2aError

Lets an executor that delegates to another agent use ? on client calls.

An AgentExecutor returns A2aResult, so without this every delegated call had to be flattened to a string, losing whether it was worth retrying. The conversion keeps what the server needs to classify the failed task (see a2a_protocol_types::failure::error_class):

ClientError	A2aError code	Failure class
Protocol(e)	e.code, with e.message and e.data unchanged	from the code
anything is_retryable — timeouts, connection failures, 429/502/503/504, TooManyPendingRequests	InternalError	Transient
Serialization (the peer sent something unreadable)	InvalidAgentResponse	Internal
everything else (bad endpoint, binding mismatch, other statuses, auth required)	InternalError	Internal

“Transient exactly when the client would retry” is deliberate: the client’s retry policy and the caller’s are then the same judgement. The class rides in data under the failure key; the server never sends data to its caller as-is, so it does not leak. The message is downstream A2A call failed: followed by this error’s text and its source chain, so nothing the client knew is lost.

use a2a_protocol_client::ClientBuilder;
use a2a_protocol_types::error::A2aResult;
use a2a_protocol_types::params::TaskQueryParams;

// The shape of an `AgentExecutor::execute` body that delegates.
async fn delegate(downstream: &str, task_id: &str) -> A2aResult<String> {
    let client = ClientBuilder::new(downstream).build()?;
    let task = client
        .get_task(TaskQueryParams {
            tenant: None,
            id: task_id.to_owned(),
            history_length: None,
        })
        .await?; // a timeout here fails the task as `Transient`
    Ok(task.text().unwrap_or_default().to_owned())
}

fn from(e: ClientError) -> A2aError

Converts to this type from the input type.

impl From<Error> for ClientError

fn from(e: Error) -> ClientError

Converts to this type from the input type.

impl From<Error> for ClientError

fn from(e: Error) -> ClientError

Converts to this type from the input type.