Enum ErrorKind 

pub enum ErrorKind {
    RateLimit,
    AuthError,
    TokenLimit,
    ServerError500,
    BadGateway502,
    ServiceUnavailable503,
    GatewayTimeout504,
    NetworkError,
    ParseError,
    Cancelled,
    Timeout,
    ScriptError,
    AuthorRaise,
    ScriptDepthExceeded,
    Panic,
    Internal,
}

Coarse error category. Use ErrorCode for the finer-grained, stable identifier that consumers should branch on; ErrorKind is the rollup every code belongs to (so a UI can show one bucket, an SDK can decide “is this retryable” without enumerating every code).

Variants

RateLimit

AuthError

TokenLimit

ServerError500

Upstream HTTP 500 — generic provider-side failure. Maybe-transient; retry with a short exponential backoff (issue #1296 split). Replaces the legacy umbrella ServerError for the 500 case specifically so retry policies and metrics can distinguish “internal server error” from “bad gateway” / “service unavailable” / “gateway timeout”.

BadGateway502

Upstream HTTP 502 — bad gateway, the provider’s edge fronted a failing origin. Retry with a short backoff (issue #1296 split).

ServiceUnavailable503

Upstream HTTP 503 — service unavailable, rate-limit-adjacent. Honour Retry-After aggressively when the provider sent one (issue #1296 split). Default backoff matches RateLimit since the remediation pattern (wait for capacity) is the same.

GatewayTimeout504

Upstream HTTP 504 — gateway timeout. The provider’s gateway didn’t get an answer from the origin in time. Use a longer base backoff since the slow side is unlikely to recover faster than the request shape itself (issue #1296 split).

NetworkError

ParseError

Cancelled

Timeout

Server-side execution-budget timeout (AKRIBES_EXECUTION_TIMEOUT), or a checkpoint that elapsed its declared on_timeout window. Distinct from Cancelled (explicit user/client cancel) so consumers can tell “the workflow was stopped on purpose” from “the workflow ran past its budget” — the latter is a service-level error, not a user action. Distinct from NetworkError’s “timeout” classification, which covers per-provider network timeouts inside a still-running execution.

ScriptError

AuthorRaise

Workflow-author-initiated failure — the LLM returned a non-success variant (Unable / a custom failure arm) and the author mapped it to fail (explicit on <V> fail or implicit no-trailer default). Distinguished from ScriptError so the workflow runner can retry the failing task up to workflow_retries times before surfacing the failure to the caller (issue #312). Retry exhaustion converts this to a ScriptError to preserve existing handler behavior.

ScriptDepthExceeded

Cross-script call(...) chain exceeded the engine’s SUBSCRIPT_MAX_DEPTH (issue #429, AKRIBES-E-SCRIPT-DEPTH).

Panic

A spawned tokio task in the engine panicked (typically unwrap() on None, divide-by-zero in stdlib, or an expect() blowing). Distinct from ScriptError because the workflow author didn’t cause it — it indicates an engine bug that should be filed. Surfaces as AKRIBES-E-INTERNAL-PANIC.

Internal

An invariant inside the engine/server was violated — a oneshot sender was dropped without sending, a deadlock was detected, an MCP protocol violation, etc. Always indicates a bug in Akribes itself, not in user code or in a third-party provider.

Implementations

impl ErrorKind

pub fn is_transient(&self) -> bool

Whether the underlying condition is expected to clear on its own — i.e. the same request retried later may succeed without any input change. Pairs with SuggestedAction::Retry.

pub fn is_server_error(&self) -> bool

True for any of the four upstream 5xx variants (#1296). Use this in places that need the umbrella “the provider returned a 5xx” check without enumerating every status. Pair with [is_transient] when the rate-limit / network-error siblings should also count.

pub fn base_backoff_ms(&self) -> Option<u64>

Base backoff for the per-error retry loop in milliseconds. Drives the per-variant retry semantics introduced by issue #1296:

Kind	Base	Rationale
RateLimit	2000	Honour Retry-After; otherwise a 2s start.
ServerError500	1000	Maybe-transient origin failure — short doubling.
BadGateway502	1000	Edge fronted a failing origin — short doubling.
ServiceUnavailable503	2000	Capacity-adjacent — start at the rate-limit cadence.
GatewayTimeout504	4000	Slow upstream — longer base before retrying.
NetworkError	1000	Connection-level recoverable.

All other variants return None (non-transient).

pub fn is_user_actionable(&self) -> bool

Whether the user (operator or workflow author) can fix this by changing something — config, script, or input. Used to gate “show actionable diagnostic UI” vs “just report it.”

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

Stable, machine-parseable identifier for the kind. Use this for wire payloads, log fields, and the error_kind DB column. Distinct from std::fmt::Display (which returns a human-readable phrase like "rate limit") and from Debug (which is intentional here but not load-bearing).

pub fn suggested_action(&self) -> SuggestedAction

What the caller should do — see SuggestedAction.

Trait Implementations

impl Clone for ErrorKind

fn clone(&self) -> ErrorKind

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ErrorKind

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ErrorKind

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ErrorKind

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

Formats the value using the given formatter.

impl Hash for ErrorKind

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ErrorKind

fn eq(&self, other: &ErrorKind) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ErrorKind

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for ErrorKind

impl Eq for ErrorKind

impl StructuralPartialEq for ErrorKind