Struct Error 

pub struct Error { /* private fields */ }

A failure with a message, optional HTTP diagnostics, and operation details.

Start with Self::message, Self::http_status, and Self::request_id. Use Self::statement_details for a failed query, Self::append_details for a rejected or uncertain append, and Self::write_details for a write timeout. A timed-out write may already have committed; reconcile it before replaying.

Self::is_retryable describes the failed operation. For a query that was already submitted, resume its Self::statement_id through crate::Client::statement_handle instead of submitting another query.

Implementations

impl Error

pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self

Create a new Error with error kind and message.

pub fn with_context(self, key: &'static str, value: impl ToString) -> Self

Add more context in error.

pub fn set_source(self, src: impl Into<Error>) -> Self

Set source for error.

Notes

If the source has been set, we will raise a panic here.

pub fn write_details(&self) -> Option<&WriteErrorDetails>

Returns client timeout details for a table append after sending began. Existing error kinds, sources, and HTTP diagnostics remain available.

pub fn append_details(&self) -> Option<&AppendErrorDetails>

Return structured table-append failure details, when available.

Examples found in repository

examples/append.rs (line 52)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;
    let table = common::write_table(&client)?;

    // Direct append sends exactly one caller-owned NDJSON request. Each value
    // is serialized as one line; JSON arrays are not accepted by this API.
    let ndjson = [
        serde_json::json!({
            "id": 1,
            "occurred_at": jiff::Timestamp::now(),
            "name": "first",
        }),
        serde_json::json!({
            "id": 2,
            "occurred_at": jiff::Timestamp::now(),
            "name": "second",
        }),
    ]
    .iter()
    .map(serde_json::to_string)
    .collect::<Result<Vec<_>, _>>()?
    .join("\n");

    match table.append(ndjson).await {
        Ok(result) => {
            println!("committed remotely: {} rows", result.num_rows_inserted);
            Ok(())
        }
        Err(error) => {
            if error.kind() == ErrorKind::AppendRowsFailed
                && matches!(
                    error.append_details().map(|details| details.status),
                    Some(AppendState::Unknown)
                )
            {
                eprintln!("commit outcome is unknown; reconcile before replaying this payload");
            }
            Err(error.into())
        }
    }
}

examples/bulk_append.rs (line 67)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;
    let table = common::write_table(&client)?;

    // The default Stop policy gives strict barriers. Local memory and request
    // concurrency are bounded independently; concurrent batches have no
    // defined commit order.
    let stream = table
        .append_stream()
        .target_batch_bytes(32 * 1024)
        .max_batch_rows(10_000)
        .flush_interval(Duration::from_secs(1))
        .max_buffered_bytes(1024 * 1024)
        .max_concurrent_batches(4)
        .attempt_timeout(Duration::from_secs(30))
        .build()?;

    let rows = (1..=10_000).map(|id| {
        serde_json::json!({
            "id": id,
            "occurred_at": jiff::Timestamp::now(),
            "name": format!("example-{id}"),
        })
    });

    let admission_error = match stream.send_all(rows).await {
        Ok(result) => {
            println!("accepted locally: {} rows", result.accepted_rows);
            None
        }
        Err(error) => {
            // There is no stream-wide abort or rollback. Settle the already
            // accepted prefix even if row production or admission stopped.
            eprintln!("row admission stopped; settling the accepted prefix: {error}");
            Some(error)
        }
    };

    match stream.shutdown().await {
        Ok(report) => {
            println!("committed remotely: {} rows", report.committed_rows);
            println!("final stream stats: {:?}", stream.stats());
        }
        Err(error) => {
            if matches!(
                error.append_details().map(|details| details.status),
                Some(AppendState::Unknown)
            ) {
                eprintln!("commit outcome is unknown; reconcile before replaying");
            } else {
                eprintln!("bulk append failed: {error}");
            }
            eprintln!("final stream stats: {:?}", stream.stats());
            return Err(error.into());
        }
    }

    if let Some(error) = admission_error {
        return Err(error.into());
    }
    Ok(())
}

pub fn statement_details(&self) -> Option<&StatementErrorDetails>

Return structured statement failure details, when available.

pub fn statement_id(&self) -> Option<Uuid>

Returns the statement identifier, when known. Use crate::Client::statement_handle to inspect the existing execution instead of resubmitting it. An identifier supplied before submission does not confirm that the server accepted it.

pub fn set_permanent(self) -> Self

Set permanent status for error.

pub fn set_temporary(self) -> Self

Set temporary status for error.

By set temporary, we indicate this error is retryable.

pub fn set_persistent(self) -> Self

Set persistent status for error.

By setting persistent, we indicate the retry should be stopped.

pub fn kind(&self) -> ErrorKind

Return the kind of this error.

Examples found in repository

examples/append.rs (line 50)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;
    let table = common::write_table(&client)?;

    // Direct append sends exactly one caller-owned NDJSON request. Each value
    // is serialized as one line; JSON arrays are not accepted by this API.
    let ndjson = [
        serde_json::json!({
            "id": 1,
            "occurred_at": jiff::Timestamp::now(),
            "name": "first",
        }),
        serde_json::json!({
            "id": 2,
            "occurred_at": jiff::Timestamp::now(),
            "name": "second",
        }),
    ]
    .iter()
    .map(serde_json::to_string)
    .collect::<Result<Vec<_>, _>>()?
    .join("\n");

    match table.append(ndjson).await {
        Ok(result) => {
            println!("committed remotely: {} rows", result.num_rows_inserted);
            Ok(())
        }
        Err(error) => {
            if error.kind() == ErrorKind::AppendRowsFailed
                && matches!(
                    error.append_details().map(|details| details.status),
                    Some(AppendState::Unknown)
                )
            {
                eprintln!("commit outcome is unknown; reconcile before replaying this payload");
            }
            Err(error.into())
        }
    }
}

pub fn code(&self) -> Option<&str>

Returns the server error code, including codes introduced by newer servers.

pub fn details(&self) -> Option<&Value>

Returns the original structured server details, when provided.

pub fn message(&self) -> &str

Return the error message.

pub fn http_status(&self) -> Option<StatusCode>

Return the HTTP response status when the error came from a server.

pub fn request_id(&self) -> Option<&str>

Return the request identifier supplied by ScopeDB or an intermediary.

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

Return the delay suggested by the HTTP Retry-After header.

pub fn is_retryable(&self) -> bool

Return whether retrying this operation is currently appropriate. For statement handles, retry on the same handle. Errors from query() or execute() after submission never indicate that resubmitting is safe.

pub fn is_temporary(&self) -> bool

Check if this error is temporary.

pub fn is_permanent(&self) -> bool

Check if this error is permanent.

pub fn is_persistent(&self) -> bool

Check if this error is persistent.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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.