Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! LLM error type.
use std::time::Duration;
use thiserror::Error;
/// Result alias used throughout the LLM crate.
pub type LlmResult<T> = Result<T, LlmError>;
/// Errors raised by LLM providers.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum LlmError {
/// Underlying HTTP failure.
#[error("http: {0}")]
Http(#[from] reqwest::Error),
/// Provider returned a non-2xx status.
#[error("provider error {status}: {body}")]
Provider {
/// HTTP status code.
status: u16,
/// Response body (truncated).
body: String,
/// Provider-requested delay before another equivalent request.
retry_after: Option<Duration>,
},
/// JSON (de)serialization failure.
#[error("serde: {0}")]
Serde(String),
/// Provider gave a response with unexpected shape (e.g. no tool
/// use block where structured output was requested).
#[error("unexpected response shape: {0}")]
UnexpectedShape(String),
/// Structured response stopped at the provider's token budget
/// (`finish_reason = "length"`): the engine ran out of output budget
/// before finishing the JSON. Terminal — a retry reproduces the same
/// truncation and doubles the spend. Carries only the configured
/// model label and the provider-reported completion token count —
/// never response content, prompt text, or secrets.
#[error(
"structured response truncated at token budget (finish_reason=length) for model {model}"
)]
TruncatedResponse {
/// Configured model label.
model: String,
/// `usage.completion_tokens` when the provider reported it.
completion_tokens: Option<u32>,
},
/// Structured request got HTTP 2xx but no usable message content
/// (`message.content` missing, empty, or whitespace-only). Terminal
/// and distinct from [`Self::TruncatedResponse`] and from a JSON
/// parse error: nothing was produced to parse.
#[error("provider returned no message content for model {model}")]
EmptyContent {
/// Configured model label.
model: String,
},
/// Configured provider lacks the env var we need.
#[error("provider not configured: {0}")]
NotConfigured(String),
/// Provider authentication failed or expired.
#[error("auth: {0}")]
Auth(String),
/// Optional local work could not start without waiting behind already
/// active work. Callers should use their non-provider fallback instead of
/// retrying or reporting the provider unhealthy.
#[error("{0} capacity is busy")]
CapacityBusy(&'static str),
/// JSON schema for structured output could not be derived.
#[error("schema: {0}")]
Schema(String),
/// Every eligible candidate in an ordered LLM fallback chain failed, or
/// every candidate's circuit was open. Carries only provider/model
/// labels and error classes/status — never response bodies or secrets.
/// See `docs/llm-provider-fallback.md`.
#[error("llm fallback chain exhausted after {attempted} candidate(s): {summary}")]
AllCandidatesFailed {
/// Number of candidates actually attempted (skipped open circuits
/// are excluded from this count).
attempted: usize,
/// Bounded `provider/model: class[ status]` summary, one entry per
/// attempt, joined with `"; "`.
summary: String,
},
}
impl LlmError {
/// Whether this failure is worth a short, bounded retry.
///
/// True only for errors that a subsequent identical request could plausibly
/// succeed on: a server-side `Provider` status (`429` or any `5xx`,
/// including Cloudflare's `52x`), or an `Http` transport timeout / connect
/// failure. Everything else — auth, schema, a malformed-request `4xx`, a
/// deserialization or unexpected-shape error — is deterministic: retrying
/// only burns another expensive call. Callers must keep the retry *short
/// and bounded* (a few attempts, seconds apart); this is not a license for
/// tenacity-style 8–128s backoff (see the cognee #2840 lesson in `lib.rs`).
#[must_use]
pub fn is_transient(&self) -> bool {
match self {
Self::Provider { status, .. } => Self::status_is_transient(*status),
Self::Http(e) => e.is_timeout() || e.is_connect(),
_ => false,
}
}
/// The status half of [`Self::is_transient`], for a call site that must
/// pick an error variant before one exists — a token endpoint answering
/// `429`/`5xx` has not rejected the credential, so it must not become an
/// `Auth` error, which is deterministic.
#[must_use]
pub fn status_is_transient(status: u16) -> bool {
status == 429 || (500..=599).contains(&status)
}
/// HTTP status captured from this error, when the failure carries one.
#[must_use]
pub fn http_status(&self) -> Option<u16> {
match self {
Self::Http(e) => e.status().map(|status| status.as_u16()),
Self::Provider { status, .. } => Some(*status),
_ => None,
}
}
/// Provider-requested delay before another equivalent request, when the
/// failed HTTP response carried a trustworthy, boundedly parsed hint.
#[must_use]
pub const fn retry_after(&self) -> Option<Duration> {
match self {
Self::Provider { retry_after, .. } => *retry_after,
_ => None,
}
}
/// Redacted error category used for health reporting and the fallback
/// chain's aggregate error — never a response body or secret.
#[must_use]
pub const fn class(&self) -> &'static str {
match self {
Self::Http(_) => "http",
Self::Provider { .. } => "provider",
Self::Serde(_) => "serde",
Self::UnexpectedShape(_) => "unexpected-shape",
Self::TruncatedResponse { .. } => "truncated-response",
Self::EmptyContent { .. } => "empty-content",
Self::NotConfigured(_) => "not-configured",
Self::Auth(_) => "auth",
Self::CapacityBusy(_) => "capacity-busy",
Self::Schema(_) => "schema",
Self::AllCandidatesFailed { .. } => "all-candidates-failed",
}
}
}
impl From<serde_json::Error> for LlmError {
fn from(value: serde_json::Error) -> Self {
Self::Serde(value.to_string())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn transient_covers_429_and_5xx_only() {
assert!(
LlmError::Provider {
status: 429,
body: String::new(),
retry_after: None,
}
.is_transient()
);
for status in [500, 502, 503, 504, 520, 524] {
assert!(
LlmError::Provider {
status,
body: String::new(),
retry_after: None,
}
.is_transient(),
"status {status} should be transient"
);
}
// A malformed-request 4xx (not 429) is deterministic — do not retry.
for status in [400, 401, 403, 404, 422] {
assert!(
!LlmError::Provider {
status,
body: String::new(),
retry_after: None,
}
.is_transient(),
"status {status} must not be treated as transient"
);
}
}
#[test]
fn deterministic_errors_are_not_transient() {
assert!(!LlmError::Auth("expired".into()).is_transient());
assert!(!LlmError::CapacityBusy("embedding").is_transient());
assert!(!LlmError::Schema("bad".into()).is_transient());
assert!(!LlmError::Serde("nope".into()).is_transient());
assert!(!LlmError::UnexpectedShape("no tool block".into()).is_transient());
assert!(!LlmError::NotConfigured("no key".into()).is_transient());
}
// A `length` stop or an empty 2xx is a definitive answer about this
// response: it is not transient, and the error must carry no response
// content in its message.
#[test]
fn truncated_and_empty_content_are_terminal_and_content_free() {
let truncated = LlmError::TruncatedResponse {
model: "qwen3.8-27b".into(),
completion_tokens: Some(4096),
};
assert_eq!(truncated.class(), "truncated-response");
assert!(!truncated.is_transient());
assert_eq!(truncated.http_status(), None);
let rendered = truncated.to_string();
assert!(rendered.contains("finish_reason=length"), "{rendered}");
assert!(rendered.contains("qwen3.8-27b"), "{rendered}");
let empty = LlmError::EmptyContent {
model: "qwen3.8-27b".into(),
};
assert_eq!(empty.class(), "empty-content");
assert!(!empty.is_transient());
assert_eq!(empty.http_status(), None);
}
#[test]
fn truncated_response_message_carries_no_content() {
let err = LlmError::TruncatedResponse {
model: "qwen3.8-27b".into(),
completion_tokens: None,
};
let rendered = err.to_string();
// Only the class, the wire fact, and the operator's own model
// label may appear — never the (truncated) completion text.
assert!(!rendered.contains('{'), "{rendered}");
assert_eq!(rendered.matches('"').count(), 0, "{rendered}");
}
#[test]
fn all_candidates_failed_is_not_transient() {
// The aggregate error is terminal: nothing is left to advance to.
assert!(
!LlmError::AllCandidatesFailed {
attempted: 2,
summary: String::new(),
}
.is_transient()
);
}
#[test]
fn http_status_reads_provider_status_only() {
assert_eq!(
LlmError::Provider {
status: 503,
body: "boom".into(),
retry_after: None,
}
.http_status(),
Some(503)
);
assert_eq!(LlmError::Schema("bad".into()).http_status(), None);
}
#[test]
fn class_is_a_stable_redacted_label_never_the_message() {
let cases: &[(LlmError, &str)] = &[
(
LlmError::Provider {
status: 500,
body: "secret upstream body".into(),
retry_after: None,
},
"provider",
),
(LlmError::Serde("nope".into()), "serde"),
(
LlmError::UnexpectedShape("no tool block".into()),
"unexpected-shape",
),
(
LlmError::TruncatedResponse {
model: "qwen3.8-27b".into(),
completion_tokens: Some(4096),
},
"truncated-response",
),
(
LlmError::EmptyContent { model: "m".into() },
"empty-content",
),
(LlmError::NotConfigured("no key".into()), "not-configured"),
(LlmError::Auth("expired".into()), "auth"),
(LlmError::CapacityBusy("embedding"), "capacity-busy"),
(LlmError::Schema("bad".into()), "schema"),
(
LlmError::AllCandidatesFailed {
attempted: 1,
summary: String::new(),
},
"all-candidates-failed",
),
];
for (err, expected) in cases {
assert_eq!(err.class(), *expected, "unexpected class for {err}");
assert!(!err.class().contains("secret upstream body"));
}
}
#[test]
fn status_is_transient_matches_is_transient() {
for status in [429u16, 500, 503, 529, 599] {
assert!(LlmError::status_is_transient(status), "{status}");
assert!(
LlmError::Provider {
status,
body: String::new(),
retry_after: None,
}
.is_transient(),
"{status} must agree with is_transient"
);
}
for status in [400u16, 401, 403, 404, 422, 600] {
assert!(!LlmError::status_is_transient(status), "{status}");
assert!(
!LlmError::Provider {
status,
body: String::new(),
retry_after: None,
}
.is_transient(),
"{status} must agree with is_transient"
);
}
}
}