Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

8.2 KB
Raw Blame
//! Hosted backend error-token parsing and provider-neutral classification.
//!
//! The OpenHuman **managed backend** (PR #870 / backend `tinyhumansai/backend#870`)
//! stamps every inference error response with a stable machine-readable
//! `errorCode` field in the JSON body, e.g.
//!
//! ```json
//! {"error":{"message":"Rate limited","errorCode":"RATE_LIMITED","retryAfter":30}}
//! ```
//!
//! The provider adapter owns parsing and emits a generic
//! [`BackendErrorClassification`] through the core registry. That value keeps
//! provider ownership, backend ownership, reportability, optional token, and
//! display kind separate. Core chat and observability code consumes those
//! fields without learning hosted token vocabulary or parsing provider
//! envelopes.

use super::managed_model::PROVIDER_LABEL;
use openhuman_embed::__host::inference_registry::{BackendErrorClassification, BackendErrorKind};

/// A recognised backend `errorCode` token (PR #870).
///
/// Unknown / future tokens are intentionally NOT represented here — they are
/// still detected as "an `errorCode` is present" by
/// [`extract_backend_error_code_token`] (so the Sentry golden rule still
/// applies), but they fall through to the substring ladder for *display*
/// classification rather than guessing a bucket.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BackendErrorCode {
    RateLimited,
    UserInsufficientCredits,
    UpstreamUnavailable,
    ModelUnavailable,
    PayloadTooLarge,
    ContextLengthExceeded,
    BadRequest,
    InternalError,
}

impl BackendErrorCode {
    /// Parse a canonical (upper-cased) token into a known variant.
    pub fn from_token(token: &str) -> Option<Self> {
        match token {
            "RATE_LIMITED" => Some(Self::RateLimited),
            "USER_INSUFFICIENT_CREDITS" => Some(Self::UserInsufficientCredits),
            "UPSTREAM_UNAVAILABLE" => Some(Self::UpstreamUnavailable),
            "MODEL_UNAVAILABLE" => Some(Self::ModelUnavailable),
            "PAYLOAD_TOO_LARGE" => Some(Self::PayloadTooLarge),
            "CONTEXT_LENGTH_EXCEEDED" => Some(Self::ContextLengthExceeded),
            "BAD_REQUEST" => Some(Self::BadRequest),
            "INTERNAL_ERROR" => Some(Self::InternalError),
            _ => None,
        }
    }
}

/// Extract the raw (upper-cased) `errorCode` token from a flattened error
/// string, or `None` when the body carries no `errorCode` field.
///
/// Returns the token **even if it is not a recognised [`BackendErrorCode`]** —
/// the mere presence of an `errorCode` means the error came through the managed
/// backend, which is what the Sentry golden rule keys on. Display
/// classification narrows further via [`BackendErrorCode::from_token`].
///
/// The key match is case-insensitive (`"errorCode"` / `"errorcode"` /
/// `"ERRORCODE"`) so a re-cased or re-serialised body still resolves; the
/// extracted **value** is upper-cased before return so callers can compare
/// against the canonical tokens regardless of how the backend cased them.
pub fn extract_backend_error_code_token(err: &str) -> Option<String> {
    // `to_ascii_lowercase` is byte-length preserving (it only remaps ASCII
    // bytes in place), so a byte index found in `lower` is also valid in the
    // original `err` — we search the lowercased copy for the key but read the
    // value out of the original to keep the token's casing intact for the
    // (defensive) upper-casing below.
    let lower = err.to_ascii_lowercase();
    const KEY: &str = "\"errorcode\"";
    let key_idx = lower.find(KEY)?;
    let after_key = &err[key_idx + KEY.len()..];
    // Skip ONLY the JSON separators (whitespace + the colon) and then require a
    // quoted string value. A non-string value (`"errorCode":null` / a number)
    // must NOT be treated as a present code — otherwise the old
    // `trim_start_matches(|c| c != '"')` skipped past the `null` and latched
    // onto the *next* key's opening quote, returning a bogus token and wrongly
    // marking the error backend-owned (CodeRabbit). `strip_prefix('"')` returns
    // `None` for a non-string value, so we bail correctly.
    let after_colon = after_key.trim_start_matches(|c: char| c.is_ascii_whitespace() || c == ':');
    let stripped = after_colon.strip_prefix('"')?;
    let end = stripped.find('"')?;
    let token = stripped[..end].trim().to_ascii_uppercase();
    if token.is_empty() {
        None
    } else {
        Some(token)
    }
}

/// Whether the flattened error string is a **managed-backend** envelope (the
/// `errorCode` contract only holds for errors that came through the OpenHuman
/// managed backend, `"OpenHuman API error (...)"` /
/// `"OpenHuman streaming API error (...)"`).
///
/// Used when callers have only a flattened string and no provider identity to
/// supply to the classifier.
pub fn is_managed_backend_envelope(err: &str) -> bool {
    let label = PROVIDER_LABEL.to_ascii_lowercase();
    let lower = err.to_ascii_lowercase();
    lower.starts_with(&format!("{label} api error"))
        || lower.starts_with(&format!("{label} streaming api error"))
        // Existing diagnostics may still carry the former host-adapter label.
        || lower.starts_with("openhuman api error")
        || lower.starts_with("openhuman streaming api error")
}

/// Whether the managed backend explicitly flagged this `BAD_REQUEST` as a
/// **malformed** payload (the client built a request the backend couldn't
/// parse), as opposed to a user-parameter rejection (an unsupported model /
/// parameter combination the user can fix).
///
/// Contract consumed from backend PR #870: the malformed variant carries a
/// `"malformed": true` flag alongside `"errorCode":"BAD_REQUEST"`. Only this
/// variant keeps paging the FE Sentry (F8/B8) — every other `errorCode` (the
/// user-param `BAD_REQUEST` included) is owned by the backend and must not
/// double-report.
pub fn body_flags_malformed(err: &str) -> bool {
    let lower = err.to_ascii_lowercase();
    const KEY: &str = "\"malformed\"";
    let Some(key_idx) = lower.find(KEY) else {
        return false;
    };
    // Whitespace-tolerant: accept `"malformed":true`, `"malformed": true`, and
    // pretty-printed `"malformed" : true` (CodeRabbit) — skip arbitrary
    // whitespace and the colon before matching the boolean literal.
    let after_key = &lower[key_idx + KEY.len()..];
    let after_colon = after_key.trim_start_matches(|c: char| c.is_ascii_whitespace() || c == ':');
    after_colon.starts_with("true")
}

/// Classify an error for the core's generic observability and chat surfaces.
pub(crate) fn classify(provider: Option<&str>, err: &str) -> BackendErrorClassification {
    let provider_owned = provider.map_or_else(
        || is_managed_backend_envelope(err),
        |provider| matches!(provider, PROVIDER_LABEL | "OpenHuman"),
    );
    let token = provider_owned
        .then(|| extract_backend_error_code_token(err))
        .flatten();
    let kind = token
        .as_deref()
        .and_then(BackendErrorCode::from_token)
        .map(|code| match code {
            BackendErrorCode::RateLimited => BackendErrorKind::RateLimited,
            BackendErrorCode::UserInsufficientCredits => BackendErrorKind::InsufficientCredits,
            BackendErrorCode::UpstreamUnavailable => BackendErrorKind::UpstreamUnavailable,
            BackendErrorCode::ModelUnavailable => BackendErrorKind::ModelUnavailable,
            BackendErrorCode::PayloadTooLarge => BackendErrorKind::PayloadTooLarge,
            BackendErrorCode::ContextLengthExceeded => BackendErrorKind::ContextLengthExceeded,
            BackendErrorCode::BadRequest => BackendErrorKind::BadRequest,
            BackendErrorCode::InternalError => BackendErrorKind::Internal,
        });
    let malformed_bad_request =
        matches!(kind, Some(BackendErrorKind::BadRequest)) && body_flags_malformed(err);
    let client_guard_leak = matches!(
        kind,
        Some(BackendErrorKind::PayloadTooLarge | BackendErrorKind::ContextLengthExceeded)
    );
    let backend_owned = provider_owned && token.is_some();
    BackendErrorClassification {
        provider_owned,
        backend_owned,
        reportable: !backend_owned || malformed_bad_request || client_guard_leak,
        token,
        kind,
        malformed_bad_request,
    }
}

#[cfg(test)]
#[path = "backend_error_code_tests.rs"]
mod tests;