Enum ClientError 

#[non_exhaustive]
pub enum ClientError {
    Http(HttpError),
    InvalidHeaderValue(InvalidHeaderValueError),
    AuthFailed(u16),
    Parse(Error),
    BlobIntegrityMismatch {
        expected: String,
        actual: String,
    },
    InvalidArgument(String),
    InvalidSession(String),
    MethodNotFound(String),
    MethodError {
        error_type: String,
        description: Option<String>,
    },
    Serialize(Error),
    SseFrameTooLarge {
        limit: usize,
    },
    ResponseTooLarge {
        actual: u64,
        limit: u64,
    },
    WebSocket(WebSocketError),
    UnexpectedResponse(String),
    RateLimited {
        retry_after: UTCDate,
    },
}

Errors produced by the base JMAP client.

Variants cover transport failures (Http, WebSocket), authentication (AuthFailed), JMAP protocol errors (MethodError, UnexpectedResponse), caller bugs (InvalidArgument, InvalidHeaderValue, Serialize), and resource-exhaustion guards (ResponseTooLarge, SseFrameTooLarge).

Marked #[non_exhaustive] so additional variants may be introduced in minor releases. See per-variant documentation for retriability guidance.

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(HttpError)

Network or TLS error from the HTTP layer. May be retriable (transient network failure) or permanent (TLS configuration error). Indicates a network or transport problem, not a JMAP protocol error.

The payload is an opaque HttpError that does not expose any third-party error type — this crate’s HTTP transport can be swapped or its major version bumped without affecting downstream callers. Use HttpError::is_timeout, HttpError::status, etc. to diagnose.

InvalidHeaderValue(InvalidHeaderValueError)

A header value could not be encoded. Indicates a caller bug — the credential string contains characters that are not valid HTTP header value characters. Not retriable.

AuthFailed(u16)

The server returned HTTP 401 (authentication failure) or 403 (authorization failure — credentials present but insufficient). Not retriable without correcting credentials.

Parse(Error)

A server response could not be parsed or did not match the expected shape. Indicates the server sent a malformed response. Not retriable without a server fix.

Construct explicitly: .map_err(ClientError::Parse).

BlobIntegrityMismatch

Downloaded blob SHA-256 does not match the expected digest. Indicates in-transit corruption or a misbehaving server. Not retriable without re-fetching metadata.

Fields

expected: String

Hex-encoded SHA-256 digest the caller asked the client to verify against.

actual: String

Hex-encoded SHA-256 digest actually computed over the downloaded bytes.

InvalidArgument(String)

A caller-supplied argument violates a precondition (e.g. empty token, colon in BasicAuth username, missing required filter field).

InvalidSession(String)

The JMAP Session object from the server was missing a required field. Indicates a server-side bug or incompatible server. Not retriable.

MethodNotFound(String)

The JMAP API response did not contain the expected method call ID. Indicates a server-side bug or unexpected response shape.

MethodError

The JMAP server returned a method-level error object (RFC 8620 §3.6). Retriability depends on error_type (e.g. serverFail may be retried; invalidArguments is not retriable).

description is None when the server omits the optional description field.

Fields

error_type: String

The type field of the JMAP method-level error object (RFC 8620 §3.6.2), e.g. "invalidArguments", "serverFail", "accountNotFound".

description: Option<String>

Optional human-readable error description (RFC 8620 §3.6.2); None when the server omits this field.

Serialize(Error)

A JMAP request could not be serialized to JSON when sending over WebSocket. Indicates a caller bug — the data structure contains non-serializable values. Not retriable.

This error is only returned by WsSession::send_request; the HTTP call() path delegates serialization to reqwest, which surfaces serialization failures as ClientError::Http.

Construct explicitly: .map_err(ClientError::Serialize).

SseFrameTooLarge

An SSE frame exceeded the configured buffer limit (ClientConfig::max_sse_frame). The stream is terminated after this error. Indicates a misbehaving or hostile server.

Fields

limit: usize

The configured per-frame buffer cap (in bytes) that was exceeded.

ResponseTooLarge

A server response body exceeded the enforced size limit. Protects against unbounded memory allocation from malicious or buggy servers. actual is in bytes (from Content-Length or actual read size).

Fields

actual: u64

Observed response size in bytes (from Content-Length or the running total of bytes read so far when streaming).

limit: u64

Configured maximum response size in bytes.

WebSocket(WebSocketError)

A WebSocket transport error (connection, framing, or TLS). May be retriable (transient network failure) or permanent (TLS config error).

The payload is an opaque WebSocketError that does not expose any third-party error type — see HttpError for the same SemVer rationale. Use WebSocketError::is_io, WebSocketError::is_protocol, etc. to diagnose.

UnexpectedResponse(String)

The server returned a response that violates the JMAP protocol (outside the Session fetch path). Examples: wrong Content-Type on an SSE connection, unexpected response shape on a non-session endpoint.

Distinct from ClientError::InvalidSession, which indicates a problem with the Session document itself. Not retriable without a server fix.

RateLimited

Server rate-limited the request. retry_after indicates when to retry.

Note (bd:JMAP-6lsm.3): this base crate does not currently produce this variant. HTTP 429 responses fall through reqwest’s error_for_status() and surface as ClientError::Http instead. The variant is part of the public contract so:

1. Extension crates that wrap or replace this crate’s transport may detect 429 + parse Retry-After themselves and produce RateLimited from their own error-conversion code.
2. Callers that want to handle rate limiting via this typed variant have a stable target to match on, even before the conversion logic lands here (tracked under bd:JMAP-6lsm.3).

If you encounter a 429 today, match on ClientError::Http and call HttpError::status to confirm Some(429). The base crate may gain native 429 → RateLimited conversion in a future minor release; the variant shape will not change in a backward-incompatible way (it is #[non_exhaustive] via the enum-level annotation, so extra fields can be added without a SemVer break).

Fields

retry_after: UTCDate

Absolute UTC instant the client should wait until before retrying, parsed from the Retry-After HTTP header (RFC 9110 §10.2.3).

Trait Implementations

impl Debug for ClientError

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

Formats the value using the given formatter.

impl Display for ClientError

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

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.