Enum BackendError 

pub enum BackendError {
    Unsupported(&'static str),
    Network(String),
    Auth(String),
    RateLimited {
        message: String,
        retry_after_seconds: Option<u32>,
    },
    Conflict(String),
    RemoteError {
        code: String,
        message: String,
    },
    Validation(String),
}

Errors that can occur when calling a PdsAdminBackend method.

Backends map their wire-level errors into these variants. The audit log (#85) records the variant + any contained message; the recordAction pipeline (#87+) decides whether to retry, surface, or log-and-continue based on the variant.

Mapping guidance for implementations

• Network-layer failures (DNS, TCP, TLS, timeout) → Self::Network. Treat as transient at the call site; the recordAction pipeline may decide to log-and-continue per A13.
• Auth failures (401 / 403, expired credentials, insufficient role) → Self::Auth. Non-transient; don’t retry without operator intervention.
• Backend rate limiting (429) → Self::RateLimited. Pass through any Retry-After hint the backend provided.
• State conflicts (already-takendown account on takedown_account, not-takendown on restore_account) → Self::Conflict. The pipeline may treat as a no-op success or a real error depending on context.
• Backend error envelopes without a specific variant → Self::RemoteError with verbatim code + message for audit forensics.
• Pre-call validation failures (malformed request constructed by cairn-mod itself) → Self::Validation. Should be rare in production; usually a cairn-mod-side bug.
• Unsupported method → Self::Unsupported. Should never reach the recordAction pipeline if #83’s action_map validation runs correctly; if it does, the operator misconfigured.

Variants

Unsupported(&'static str)

The backend does not support this method on this PDS. Example: OzoneBackend::apply_label (per A5 — labels stay native to cairn-mod’s subscribeLabels).

This variant is config-time-detectable; the recordAction pipeline should never see it at runtime if the action_map validation in #83 ran correctly. If it does, that’s a bug — log loudly and surface to the operator.

Network(String)

Network-layer failure (DNS, TCP, TLS, timeout). Transient by default — the recordAction pipeline may decide to log-and-continue per A13’s “fail loud, let the operator decide” posture; v1.8 may add automatic retry.

Auth(String)

Authentication or authorization failure. Either the configured credentials are wrong, the credentials’ role is insufficient, or the credentials expired. Non-transient: don’t retry without operator intervention.

RateLimited

Backend signaled rate limiting. retry_after_seconds carries the backend’s hint when one was provided (typically via a Retry-After HTTP header).

Fields

message: String

Backend-supplied or client-synthesized message describing the rate-limit context.

retry_after_seconds: Option<u32>

Optional retry hint in seconds.

Conflict(String)

The action conflicts with the backend’s current state. Examples: trying to restore_account an account that isn’t taken down; trying to takedown_account an account that’s already taken down. The recordAction pipeline may treat this as a no-op success or a real error depending on context.

RemoteError

Backend returned an error envelope cairn-mod doesn’t have a specific variant for. Carries the backend’s error code and message verbatim for audit-log forensics.

Fields

code: String

Backend-supplied error code (typically the value of XRPC’s error field, or an HTTP status reason phrase).

message: String

Backend-supplied human-readable message.

Validation(String)

Request validation failed before the call could be made. Distinct from Self::Conflict (post-call) — Validation means the call was malformed at construction time. Should be rare in production; usually indicates a cairn-mod-side bug.

Trait Implementations

impl Debug for BackendError

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

Formats the value using the given formatter.

impl Display for BackendError

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

Formats the value using the given formatter.

impl Error for BackendError

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.