Enum ClientError 

#[non_exhaustive]
pub enum ClientError {
    Http(HttpError),
    InvalidHeaderValue(InvalidHeaderValueError),
    AuthFailed(u16),
    Parse(ParseError),
    BlobIntegrityMismatch {
        expected: String,
        actual: String,
    },
    InvalidArgument(String),
    InvalidSession(String),
    MethodNotFound(String),
    MethodError(JmapError),
    Serialize(SerializeError),
    SseFrameTooLarge {
        limit: usize,
    },
    ResponseTooLarge {
        actual: u64,
        limit: u64,
    },
    WebSocket(WebSocketError),
    WsClosed {
        code: u16,
        reason: String,
    },
    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(ParseError)

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.

The payload is an opaque ParseError that does not expose the underlying JSON parser’s error type — the variant is insulated from a future parser swap. Construct explicitly: .map_err(ClientError::from_parse) (or .map_err(jmap_base_client::ClientError::from_parse) from outside the crate). Pattern-match via ClientError::Parse(e) => e.line(), e.column(), e.classify() — see ParseError.

BlobIntegrityMismatch

Blob SHA-256 mismatch on upload or download. Indicates in-transit corruption or a misbehaving server. Not retriable without re-fetching metadata.

Field semantics across both call sites (bd:JMAP-6r7c.10)

The same variant is emitted from both upload and download paths and the role of each field is constant across paths:

• expected is the pre-stated digest the client was comparing against — i.e. the value that should hold if the bytes are intact.
• actual is the freshly-observed digest the client just computed or just learned.

The source of each value depends on which call produced the error:

Call site	expected	actual
JmapClient::upload_blob	client’s own SHA-256 of the bytes about to be uploaded	server’s reported SHA-256 in the upload response
JmapClient::download_blob	DownloadBlobParams::expected_sha256 supplied by the caller (typed jmap_cid_types::Sha256, guaranteed canonical lowercase)	client’s SHA-256 of the actually-received bytes
JmapClient::upload_blob_stream	client’s SHA-256 of the bytes streamed to the server	server’s reported SHA-256 in the upload response
JmapClient::download_blob_stream (final stream item)	DownloadBlobParams::expected_sha256 supplied by the caller	client’s SHA-256 of all streamed bytes

Both digests are canonical 64-character lowercase hex (per draft-atwood-jmap-cid-00 §2 ABNF).

Fields

expected: String

Pre-stated SHA-256 hex digest the client was comparing against. On upload, this is the client’s own pre-upload computation; on download, this is the caller-supplied DownloadBlobParams::expected_sha256 (typed jmap_cid_types::Sha256, guaranteed canonical lowercase).

actual: String

Freshly-observed SHA-256 hex digest. On upload, this is the server-reported digest from the upload response. On download, this is the client’s own digest over the received 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(JmapError)

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

The payload keeps every property jmap_types::JmapError models (type, description, limit), so for example a tooManyChanges error’s limit reaches the caller. method_error_details returns any other properties. An error object whose type is missing, or whose type, description or limit is not of its RFC 8620 type (for example a string or negative limit), is ClientError::Parse: RFC 8620 §3.6.2 says it “MUST have a type property”.

Serialize(SerializeError)

A caller-supplied value could not be serialized to JSON. Indicates a caller bug — the data structure contains values JSON cannot represent. Not retriable.

Returned by to_args (and so by every extension client method that serializes a caller-supplied argument) and by WsSession::send_request. The HTTP call() path delegates request serialization to reqwest, which surfaces serialization failures as ClientError::Http.

The payload is an opaque SerializeError that does not expose the underlying JSON serializer’s error type. Construct explicitly: .map_err(ClientError::from_serialize). Pattern-match via ClientError::Serialize(e) => e.line(), e.column(), e.classify() — see SerializeError.

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.

WsClosed

The server closed the WebSocket with a Close frame whose status code asks the client to act, rather than ending the stream cleanly.

Produced by WsSession::next_frame for status code 1008 (Policy Violation, RFC 6455 §7.4.1). A JMAP Chat server closes with 1008 when the connection’s credentials expire (draft-atwood-jmap-chat-wss-00 §Authentication and Identity), so the caller should refresh credentials before reconnecting. Any other Close frame still ends the stream with None. The connection is closed: do not call next_frame again.

Fields

code: u16

The Close frame’s status code (RFC 6455 §7.4), e.g. 1008.

reason: String

The Close frame’s reason text; empty when the server sent none.

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.

Produced for an HTTP 429 (Too Many Requests) response from JmapClient::fetch_session, JmapClient::call, JmapClient::upload_blob and JmapClient::download_blob (and the _session wrappers that delegate to them). Extension crates also produce it, e.g. for a rateLimit SetError. A 429 on the event-source connection still surfaces as ClientError::Http so JmapClient::subscribe_events_reconnecting can keep retrying it.

retry_after comes from the Retry-After header (RFC 9110 §10.2.3): a delay-seconds value is added to the time the response was received, and an HTTP-date in any of the three RFC 9110 §5.6.7 formats is used as given. When the header is absent or unparseable, retry_after is the time the response was received — the server gave no delay, so the caller should apply its own backoff. Instants past 9999-12-31T23:59:59Z are clamped to it.

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).

Implementations

impl ClientError

pub fn from_parse(e: Error) -> Self

Convert a serde_json::Error from a deserialize / parse step into a ClientError::Parse variant carrying an opaque ParseError payload (bd:JMAP-6r7c.26).

Public because extension client crates (jmap-mail-client, jmap-chat-client, etc.) need to surface their own JSON parse failures as ClientError::Parse. Use in .map_err:

let val: T = serde_json::from_slice(&bytes)
    .map_err(jmap_base_client::ClientError::from_parse)?;

A future JSON-parser swap would deprecate this constructor in favor of an analogous one for the new parser; the variant payload type (ParseError) stays stable.

pub fn from_serialize(e: Error) -> Self

Convert a serde_json::Error from a serialize step into a ClientError::Serialize variant carrying an opaque SerializeError payload (bd:JMAP-6r7c.26).

Public for the same reason as from_parse.

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.