Error Types

ClientError          (transport/connection base — embedded by select domain errors)
  ├── NotConnected
  ├── Socket(SocketError)
  ├── EncryptSend(EncryptSendError)
  ├── NotLoggedIn
  ├── Iq(IqError)
  └── Internal(anyhow::Error)

ConnectError          (Client::connect, wait_for_socket, wait_for_connected)
  ├── AlreadyConnected
  ├── NotActivated
  ├── Shutdown
  ├── Paused
  ├── Timeout { stage: ConnectStage, timeout: Duration }
  ├── Version(anyhow::Error)
  ├── Transport(anyhow::Error)
  └── Handshake(HandshakeError)

SignalMaintenanceError  (Client::rotate_signed_pre_key, Client::flush_pending_signal_state)
  ├── CorruptKey(String)
  ├── Storage(anyhow::Error)
  ├── Iq(IqError)
  ├── Signal(SignalProtocolError)
  ├── DrainCommitFailed
  └── DrainShuttingDown

MessageEditError      (EncryptedEdit / SecretEncrypted target-key resolvers)
  ├── InvalidTargetJid { field, source: JidError }
  └── MissingTargetSender

IqError              (IQ request failures — embedded by most domain errors)
  ├── Timeout
  ├── NotConnected
  ├── Socket(SocketError)
  ├── EncryptSend(EncryptSendError)
  ├── ClientState(Box<ClientError>)
  ├── Disconnected(Box<Node>)
  ├── ServerError
  ├── UnexpectedResponseType
  ├── InternalChannelClosed
  ├── DuplicateRequestId(String)
  ├── EncodeError
  └── ParseError

BotMessageError      (wacore::bot_message::decrypt_bot_message — wacore crate, not whatsapp_rust)
  ├── InvalidSecretLength
  ├── InvalidIvLength
  ├── PayloadTooShort
  ├── KeyDerivation
  └── AuthenticationFailed

pub trait ErrorChainExt {
    fn sources(&self) -> Sources<'_>;
    fn server_rejection(&self) -> Option<ServerRejection<'_>>;
    fn http_status(&self) -> Option<u16>;
    fn is_timeout(&self) -> bool;
    fn is_transport_unavailable(&self) -> bool;
    fn store_failure(&self) -> Option<&StoreError>;
}

use whatsapp_rust::ErrorChainExt;

match client.groups().set_description(&jid, Some(desc), PreviousDescription::Resolve).await {
    Ok(_) => {}
    Err(e) if e.is_transport_unavailable() => { /* retry once reconnected */ }
    Err(e) => {
        if let Some(rejection) = e.server_rejection() {
            eprintln!("server said {}: {}", rejection.code, rejection.text);
        } else {
            eprintln!("group update failed: {e}");
        }
    }
}

let cause: &(dyn std::error::Error + 'static) = err.as_ref();
if cause.is_timeout() { /* ... */ }

use whatsapp_rust::ErrorChainExt;

match client.download(downloadable).await {
    Ok(bytes) => { /* ... */ }
    Err(e) => {
        let cause: &(dyn std::error::Error + 'static) = e.as_ref();
        match cause.http_status() {
            // 500/502/503/504 are the CDN statuses normally worth a retry;
            // 501/505 mean the request itself is unsupported and won't
            // succeed on a resend. Apply your own policy per status.
            Some(429) | Some(500) | Some(502) | Some(503) | Some(504) => {
                /* back off and retry later */
            }
            Some(status) => eprintln!("CDN refused with {status}: {e}"),
            None => eprintln!("no HTTP refusal status recoverable, inspect the cause: {e}"),
        }
    }
}

#[non_exhaustive]
pub struct ServerRejection<'a> {
    pub code: u16,
    pub text: &'a str,
    pub error_type: Option<&'a str>,
    pub backoff: Option<u32>,
}

pub struct RejectionStanza(Arc<OwnedNodeRef>);

impl RejectionStanza {
    /// The preserved node behind its refcount, for a caller that wants to keep or share it.
    pub fn as_arc(&self) -> &Arc<OwnedNodeRef>;
    /// Takes the preserved node out, consuming the wrapper.
    pub fn into_arc(self) -> Arc<OwnedNodeRef>;
}

impl From<Arc<OwnedNodeRef>> for RejectionStanza { /* ... */ }

impl Deref for RejectionStanza {
    type Target = OwnedNodeRef;
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("HTTP status {status}")]
pub struct HttpStatusError {
    pub status: u16,
}

#[non_exhaustive]
pub enum SendError {
    #[error("{0}")]
    Client(ClientError),
    #[error("client is not logged in")]
    NotLoggedIn,
    #[error("IQ request failed: {0}")]
    Iq(#[from] IqError),
    #[error("invalid send request: {0}")]
    InvalidRequest(String),
    #[error("{0}")]
    NoRecipientDevice(#[source] wacore::send::NoRecipientDeviceError),
    #[error("{0}")]
    PrimaryDeviceRejected(#[source] wacore::send::PrimaryDeviceRejected),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum NoRecipientDeviceError {
    #[error("encryption failed for all {attempted} recipient device(s)")]
    EncryptionFailed {
        attempted: usize,
        #[source]
        source: anyhow::Error,
    },
    #[error("no device resolved for the recipient")]
    Unresolved,
}

#[non_exhaustive]
pub enum GroupError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Mex(#[from] MexError),
    #[error("invalid group request: {0}")]
    InvalidRequest(String),
    #[error("the group description changed since it was read")]
    DescriptionConflict,
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum BlockingError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("invalid blocklist target: {0}")]
    InvalidJid(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum BusinessError {
    #[error("MEX request failed")]
    Mex(#[from] MexError),
    #[error("IQ request failed")]
    Request(#[from] IqError),
    #[error("invalid business profile update")]
    InvalidUpdate(#[from] BusinessProfileUpdateError),
    #[error("malformed {operation} response: {detail}")]
    MalformedResponse {
        operation: &'static str,
        detail: String,
    },
}

#[non_exhaustive]
pub enum AppStateError {
    #[error("invalid app-state request: {0}")]
    InvalidRequest(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum ChatStateError {
    #[error("{0}")]
    Client(#[from] ClientError),
}

#[non_exhaustive]
pub enum CommunityError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Mex(#[from] MexError),
    #[error("{0}")]
    Group(#[from] GroupError),
    #[error("invalid community request: {0}")]
    InvalidRequest(String),
}

#[non_exhaustive]
pub enum ContactError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("unsupported contact JID: {0}")]
    InvalidJid(String),
    #[error("{0}")]
    Username(#[from] UsernameLookupError),
}

#[non_exhaustive]
pub enum NewsletterError {
    #[error("{0}")]
    Mex(#[from] MexError),
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Client(#[from] ClientError),
    #[error("invalid newsletter request: {0}")]
    InvalidRequest(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum PollError {
    #[error("{0}")]
    Send(#[from] SendError),
    #[error("invalid poll: {0}")]
    InvalidPoll(String),
    #[error("client is not logged in")]
    NotLoggedIn,
    #[error("poll vote crypto failed: {0}")]
    Crypto(#[source] anyhow::Error),
}

#[non_exhaustive]
pub enum ProfileError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Client(#[from] ClientError),
    #[error("invalid argument: {0}")]
    InvalidArgument(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum SignalError {
    #[error("{0}")]
    Protocol(#[from] SignalProtocolError),
    #[error("unsupported signal operation: {0}")]
    Unsupported(String),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum TcTokenError {
    #[error("{0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Store(#[from] StoreError),
}

#[non_exhaustive]
pub enum MediaReuploadError {
    #[error("{0}")]
    Client(#[from] ClientError),
    #[error("client is not logged in")]
    NotLoggedIn,
    #[error("invalid media reupload request: {0}")]
    InvalidRequest(String),
    #[error("media retry notification timed out")]
    Timeout,
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum PresenceError {
    #[error("cannot send presence without a push name set")]
    PushNameEmpty,
    #[error("{0}")]
    Client(#[from] ClientError),
    #[error("{0}")]
    Other(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum ConnectError {
    #[error("client is already connected")]
    AlreadyConnected,
    #[error("client construction did not activate")]
    NotActivated,
    #[error("client has been shut down")]
    Shutdown,
    #[error("client is paused")]
    Paused,
    #[error("{stage} timed out after {timeout:?}")]
    Timeout {
        stage: ConnectStage,
        timeout: std::time::Duration,
    },
    #[error("failed to resolve app version")]
    Version(#[source] anyhow::Error),
    #[error("failed to open transport")]
    Transport(#[source] anyhow::Error),
    #[error("{0}")]
    Handshake(#[from] crate::handshake::HandshakeError),
}

#[non_exhaustive]
pub enum ConnectStage {
    /// Resolving the app version advertised to the server.
    VersionFetch,
    /// Opening the underlying transport.
    Transport,
    /// Waiting for the noise socket, which is ready before login.
    Socket,
    /// Waiting for login plus the critical app state sync to finish.
    Ready,
}

#[non_exhaustive]
pub enum SignalMaintenanceError {
    #[error("corrupt signed pre-key material: {0}")]
    CorruptKey(String),
    #[error("signal storage failure: {0}")]
    Storage(#[source] anyhow::Error),
    #[error("IQ request failed: {0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Signal(#[from] SignalProtocolError),
    #[error(
        "inbound drain batch commit failed; Signal cache left unflushed so the server redelivers"
    )]
    DrainCommitFailed,
    #[error("client dropping while inbound drain is active; skipping Signal flush")]
    DrainShuttingDown,
}

#[non_exhaustive]
pub enum MessageEditError {
    #[error("invalid {field} in target message key")]
    InvalidTargetJid {
        field: &'static str,
        #[source]
        source: JidError,
    },
    #[error("target message key missing participant and remote_jid")]
    MissingTargetSender,
}

#[non_exhaustive]
pub enum BotMessageError {
    InvalidSecretLength,
    InvalidIvLength,
    PayloadTooShort,
    KeyDerivation,
    AuthenticationFailed,
}

pub enum BotMessageFailure {
    Envelope,
    Secret,
    Authentication,
}

#[non_exhaustive]
pub enum ClientError {
    #[error("client is not connected")]
    NotConnected,
    #[error("client is not logged in")]
    NotLoggedIn,
    #[error("socket error: {0}")]
    Socket(SocketError),
    #[error("encrypt/send error: {0}")]
    EncryptSend(EncryptSendError),
    #[error("IQ request failed: {0}")]
    Iq(#[from] IqError),
    #[error("{0}")]
    Internal(#[from] anyhow::Error),
}

#[non_exhaustive]
pub enum IqError {
    #[error("IQ request timed out")]
    Timeout,
    #[error("client is not connected")]
    NotConnected,
    #[error("socket error")]
    Socket(#[from] SocketError),
    #[error("encrypted send pipeline failed")]
    EncryptSend(#[from] EncryptSendError),
    #[error("client state prevented send")]
    ClientState(#[source] Box<ClientError>),  // boxed to break the ClientError<->IqError cycle
    #[error("received disconnect node during IQ wait: {0:?}")]
    Disconnected(Box<Node>),
    #[error("received a server error response: code={code}, text='{text}'")]
    ServerError {
        code: u16,
        text: String,
        error_type: Option<String>,
        backoff: Option<u32>,
        response: RejectionStanza, // added in PR #1257
    },
    #[error("received unexpected IQ response type: {got:?}")]
    UnexpectedResponseType { got: Option<String> },
    #[error("internal channel closed unexpectedly")]
    InternalChannelClosed,
    #[error("IQ request ID is already in flight: {0}")]
    DuplicateRequestId(String),
    #[error("failed to encode IQ request")]
    EncodeError(#[source] anyhow::Error),
    #[error("failed to parse IQ response")]
    ParseError(#[from] anyhow::Error),
}

// Before — still compiles unchanged
async fn my_fn() -> anyhow::Result<()> {
    client.send_message(jid, msg).await?;  // SendError: Into<anyhow::Error>
    Ok(())
}

// Before
match client.send_message(jid, msg).await {
    Ok(r) => { /* ... */ }
    Err(e) => eprintln!("send failed: {e}"),
}

// After — match specific variants
use whatsapp_rust::SendError;
match client.send_message(jid, msg).await {
    Ok(r) => { /* ... */ }
    Err(SendError::NotLoggedIn) => eprintln!("not authenticated"),
    Err(SendError::Iq(e)) => eprintln!("IQ failed: {e}"),
    Err(SendError::InvalidRequest(msg)) => eprintln!("bad request: {msg}"),
    Err(e) => eprintln!("send failed: {e}"),
}

// Before
Err(IqError::ClientState(e)) => { /* e: ClientError */ }

// After — dereference the box
Err(IqError::ClientState(e)) => { /* *e: ClientError */ }

// Before
if let Err(e) = client.connect().await {
    if e.downcast_ref::<ClientError>().is_some_and(|e| matches!(e, ClientError::AlreadyConnected)) {
        // ...
    }
}
client.logout().await?;

// After
use whatsapp_rust::ConnectError;
if let Err(e) = client.connect().await {
    if matches!(e, ConnectError::AlreadyConnected) {
        // ...
    }
}
client.logout().await; // infallible — no `?` needed anymore

// Before (internal to this crate — the IqError check isn't public API)
fn is_transport_unavailable(err: &anyhow::Error) -> bool {
    err.chain().any(|cause| {
        cause
            .downcast_ref::<ClientError>()
            .is_some_and(ClientError::is_transport_unavailable)
            || cause
                .downcast_ref::<IqError>()
                .is_some_and(|iq| matches!(iq, IqError::NotConnected | IqError::Disconnected(_) | IqError::InternalChannelClosed))
    })
}

// After — works the same from inside or outside the crate
use whatsapp_rust::ErrorChainExt;
fn is_transport_unavailable(err: &anyhow::Error) -> bool {
    let cause: &(dyn std::error::Error + 'static) = err.as_ref();
    cause.is_transport_unavailable()
}

// Before — fragile string matching
match client.download(downloadable).await {
    Err(e) if e.to_string().contains("401") || e.to_string().contains("403") => {
        // ...
    }
    Err(e) => eprintln!("download failed: {e}"),
    Ok(bytes) => { /* ... */ }
}

// After
use whatsapp_rust::ErrorChainExt;
match client.download(downloadable).await {
    Err(e) => {
        let cause: &(dyn std::error::Error + 'static) = e.as_ref();
        match cause.http_status() {
            Some(401) | Some(403) => { /* ... */ }
            Some(status) => eprintln!("download refused with {status}: {e}"),
            None => eprintln!("download failed: {e}"),
        }
    }
    Ok(bytes) => { /* ... */ }
}

// Still works unchanged
match err {
    IqError::ServerError { code, text, .. } => { /* ... */ }
    // ...
}

// Before — breaks with E0027 once `response` is added
IqError::ServerError { code, text, error_type, backoff } => { /* ... */ }

// After
IqError::ServerError { code, text, error_type, backoff, .. } => { /* ... */ }

// Before
IqError::ServerError {
    code,
    text,
    error_type,
    backoff,
}

// After — pass the response the rejection came with
IqError::ServerError {
    code,
    text,
    error_type,
    backoff,
    response: response.into(), // response: Arc<OwnedNodeRef>, RejectionStanza converts via `.into()`
}

let node = wacore_binary::builder::NodeBuilder::new("iq")
    .attr("type", "error")
    .children([/* ... */])
    .build();
let packed = wacore_binary::marshal::marshal(&node).expect("marshals");
let node_bytes = wacore_binary::util::unpack(&packed).expect("unpacks").into_owned();
let response: Arc<OwnedNodeRef> = Arc::new(OwnedNodeRef::new(node_bytes).expect("decodes"));

// Before
let err: IqError = wacore_err.into();

// After — pass the response the classification failure was read from
let err = IqError::from_response(wacore_err, &response);

// Before
match decrypt_bot_message(message_secret, enc_iv, enc_payload, &ctx) {
    Ok(plaintext) => { /* ... */ }
    Err(e) => eprintln!("bot message decrypt failed: {e}"),
}

// After — match specific variants, or classify by stage
use wacore::bot_message::{BotMessageError, BotMessageFailure};

match decrypt_bot_message(message_secret, enc_iv, enc_payload, &ctx) {
    Ok(plaintext) => { /* ... */ }
    Err(e @ BotMessageError::AuthenticationFailed) => eprintln!("tampered or wrong secret: {e}"),
    Err(e) => match e.stage() {
        BotMessageFailure::Envelope => eprintln!("malformed envelope: {e}"),
        BotMessageFailure::Secret => eprintln!("bad secret: {e}"),
        BotMessageFailure::Authentication => eprintln!("authentication failed: {e}"),
    },
}

// Before — `Ok` did not guarantee the recipient could read this message
match client.send_message(to.clone(), message).await {
    Ok(result) => { /* looked like success even with no recipient device reached */ }
    Err(e) => eprintln!("send failed: {e}"),
}

// After — match the new variant to detect the specific failure
use whatsapp_rust::{Freshness, SendError, send::SendOptions};
match client.send_message(to.clone(), message.clone()).await {
    Ok(result) => { /* ... */ }
    Err(SendError::NoRecipientDevice(e)) => {
        eprintln!("nothing reached the recipient: {e}");
        // Force a device-list refresh before retrying — an immediate resend
        // with the same (cached) options would hit the same empty result.
        let options = SendOptions::default().with_device_freshness(Freshness::Refresh);
        client.send_message_with_options(to.clone(), message, options).await?;
    }
    Err(e) => eprintln!("send failed: {e}"),
}

// Before — Ok told you the stanza was sent, nothing about who got it
// (send_message does not wait for the server's ack before returning)
let result = client.send_message(to.clone(), message).await?;

// After — inspect the DM fan-out when the caller's policy cares
let result = client.send_message(to.clone(), message).await?;
if result.recipient_fanout.as_ref().is_some_and(|f| f.is_partial()) {
    eprintln!("message {} did not reach every device", result.message_id);
}

match client.send_message(to.clone(), message).await {
    Ok(result) => { /* ... */ }
    Err(SendError::PrimaryDeviceRejected(e)) => {
        // The named device lists are already refreshed — retry immediately.
        eprintln!("a primary device was rejected fetching pre-keys: {e}");
    }
    Err(e) => eprintln!("send failed: {e}"),
}

// Before
let edit_id: String = client.edit_message(&chat_jid, &original_id, new_content).await?;
client.revoke_message(&chat_jid, &message_id, RevokeType::Sender).await?;
client.pin_message(chat_jid.clone(), key.clone(), PinDuration::Days7).await?;

// After — the id moves onto `message_id`, and `message` is what this crate built
let edit = client.edit_message(&chat_jid, &original_id, new_content).await?;
let edit_id: &str = &edit.message_id;

let revoke = client.revoke_message(&chat_jid, &message_id, RevokeType::Sender).await?;
let pin = client.pin_message(chat_jid.clone(), key.clone(), PinDuration::Days7).await?;