Enum CratestackError 

#[non_exhaustive]
pub enum CratestackError {
    BadRequest(String),
    NotAcceptable(String),
    Unauthorized(String),
    UnsupportedMediaType(String),
    Forbidden(String),
    NotFound(String),
    Conflict(String),
    ConflictTyped(DbErrorInfo),
    TransactionAborted(TransactionAbort),
    Validation(String),
    PreconditionFailed(String),
    Codec(String),
    Database(String),
    DatabaseTyped(DbErrorInfo),
    Internal(String),
    Unavailable(String),
    TooManyRequests(String),
    AuthRefused(AuthRefusal),
}

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.

BadRequest(String)

4xx — String is the public message returned to the client.

NotAcceptable(String)

Unauthorized(String)

UnsupportedMediaType(String)

Forbidden(String)

NotFound(String)

Conflict(String)

ConflictTyped(DbErrorInfo)

Conflict (409) with structured database information preserved from the driver — e.g. a unique-constraint violation. Prefer this over Conflict(String) when the conflict originates from a database error so CratestackError::db_sqlstate / CratestackError::db_constraint keep working for callers that inspect the typed fields regardless of whether the error surfaced as a 500 (DatabaseTyped) or a 409 (ConflictTyped).

TransactionAborted(TransactionAbort)

409 — an @isolation transaction was rolled back because of concurrent updates (SQLSTATE 40001/40P01, kept in info.sqlstate) and its retries ran out. Nothing that transaction wrote was committed, and the same request is expected to succeed when sent again — unlike Self::Conflict, which a retry repeats. info.detail is the fixed public message; the driver’s text is never carried. It is final: it is never classified as retriable itself, so an outer retry loop it propagates into does not run again because of it. An idempotency layer releases the key instead of recording it only when the dispatch that answered is the @isolation procedure whose own retries ran out (TransactionAbort::ownership, Self::is_idempotency_replayable).

Validation(String)

PreconditionFailed(String)

Codec(String)

5xx — String is operator-only detail. Never returned to clients; the public message is a fixed canned string per variant.

Database(String)

Database error with only a stringified detail. Preserved for back-compat; new code should prefer DatabaseTyped produced by cratestack_sqlx::cratestack_error_from_sqlx.

DatabaseTyped(DbErrorInfo)

Database error with structured information preserved from the driver.

Use CratestackError::db_sqlstate and CratestackError::db_constraint to access the typed fields without matching on this variant directly.

Internal(String)

Unavailable(String)

503 — the operation cannot proceed right now, but a retry (from scratch, not a resume) may succeed later. String is the public, safe-to-expose message, mirroring the other 4xx-style variants above.

Introduced for @@subscribe SSE backpressure overflow (docs/design/rpc-transport.md §3.4/§3.4a: “bounded per-subscription send buffer; on overflow, emit Error{code:"unavailable"}”) — the first caller of the RPC binding’s already-reserved "unavailable" code.

TooManyRequests(String)

429 — the caller exceeded a rate limit. String is the public, safe-to-expose message, same treatment as the 4xx variants above.

Introduced for cratestack-axum’s RateLimitLayer (cratestack#846): the throttled response used to be a hand-built text/plain 429 with no error envelope at all, so a generated client decoded it as “unrecognized error body” instead of a typed code. Expressing the throttle as a CratestackError lets that response go through the exact same encode path every other error in the stack takes, rather than the layer inventing a second body shape.

AuthRefused(AuthRefusal)

401 or 403 — an AuthProvider refused the request and chose how the refusal reads: extra envelope members, details and WWW-Authenticate challenges (cratestack#1208). The code stays UNAUTHORIZED or FORBIDDEN. Built by AuthRefusal::into_error.

Implementations

impl CratestackError

pub fn is_idempotency_replayable(&self) -> bool

Whether an idempotency layer may record this outcome and replay it to a later call under the same Idempotency-Key. false for two outcomes the answering dispatch owns, after which nothing was committed, so the layer releases the reservation instead and the same key can be sent again:

• a Self::TransactionAborted whose ownership is AbortOwnership::Claimed: the dispatch’s own transaction ran out of retries. Any other TransactionAborted — one a caller propagated out of its own body — is recorded, because that caller may have committed work before propagating it.
• a refusal the generated dispatch produced before any body ran (AuthRefusal::is_dispatch_owned, cratestack#1261), so a client that renews its credential or steps up can send the same request again under the same key. A refusal a body returned is recorded, for the same reason.

impl CratestackError

pub fn auth_challenges(&self) -> &[String]

The WWW-Authenticate header values the response carries: an [AuthRefusal]’s challenges, and none for every other error.

pub fn into_response(self) -> CratestackErrorResponse

impl CratestackError

pub fn code(&self) -> &'static str

pub fn status_code(&self) -> StatusCode

pub fn public_message(&self) -> Cow<'_, str>

Public, safe-to-expose message returned in HTTP responses.

For 4xx variants this is the caller-supplied string. For 5xx variants this is a fixed canned message; the caller-supplied string flows to detail instead and is recorded via tracing only.

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

Operator-only detail string. For 5xx variants this is the message supplied at construction time; for 4xx variants this returns the same string as public_message (callers are expected to pre-redact 4xx messages they emit).

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

Returns the SQLSTATE code if this is a DatabaseTyped error with a known code (e.g. "23505" for unique_violation).

Always returns None for the legacy Database(String) variant; to get typed access, use cratestack_sqlx::cratestack_error_from_sqlx at the conversion site.

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

Returns the constraint name if this is a DatabaseTyped error that carries constraint information (e.g. "accounts_email_key").

Always returns None for the legacy Database(String) variant; to get typed access, use cratestack_sqlx::cratestack_error_from_sqlx at the conversion site.

Trait Implementations

impl Debug for CratestackError

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

Formats the value using the given formatter.

impl Display for CratestackError

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

Formats the value using the given formatter.

impl Error for CratestackError

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.