use std::fmt;
use std::time::Duration;
use thiserror::Error;
use crate::retry::RetrySource;
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ErrorKind {
Authentication,
PermissionDenied,
NotFound,
InvalidRequest,
ContextLengthExceeded,
ContentFiltered,
RateLimited,
Overloaded,
Timeout,
Connection,
Cancelled,
Decode,
StreamProtocol,
ProviderInternal,
Unsupported,
Configuration,
Normalization,
Tool,
MaxSteps,
Unknown,
}
impl ErrorKind {
pub const fn as_str(self) -> &'static str {
match self {
Self::Authentication => "authentication",
Self::PermissionDenied => "permission_denied",
Self::NotFound => "not_found",
Self::InvalidRequest => "invalid_request",
Self::ContextLengthExceeded => "context_length_exceeded",
Self::ContentFiltered => "content_filtered",
Self::RateLimited => "rate_limited",
Self::Overloaded => "overloaded",
Self::Timeout => "timeout",
Self::Connection => "connection",
Self::Cancelled => "cancelled",
Self::Decode => "decode",
Self::StreamProtocol => "stream_protocol",
Self::ProviderInternal => "provider_internal",
Self::Unsupported => "unsupported",
Self::Configuration => "configuration",
Self::Normalization => "normalization",
Self::Tool => "tool",
Self::MaxSteps => "max_steps",
Self::Unknown => "unknown",
}
}
pub const fn is_retryable(self) -> bool {
matches!(
self,
Self::RateLimited
| Self::Overloaded
| Self::Timeout
| Self::Connection
| Self::ProviderInternal
)
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProviderErrorInfo {
pub code: Option<String>,
pub error_type: Option<String>,
pub status: Option<String>,
pub message_bytes: Option<usize>,
pub details_count: usize,
}
#[derive(Error)]
pub enum Error {
#[error("missing API key: {0}")]
MissingApiKey(String),
#[error("HTTP request failed")]
Http(#[source] reqwest::Error),
#[error("request cancelled")]
Cancelled,
#[error("request timed out: {0}")]
Timeout(String),
#[error("invalid JSON: {0}")]
Json(#[from] serde_json::Error),
#[error("stream protocol error: {0}")]
StreamProtocol(String),
#[error("provider stream error (raw payload redacted)")]
ProviderStream(String),
#[error("response exceeded {resource} limit of {limit}")]
ResponseLimit {
resource: &'static str,
limit: usize,
},
#[error("{provider} returned HTTP {status}")]
Api {
provider: &'static str,
status: u16,
body: String,
retry_after: Option<Duration>,
retry_source: Option<RetrySource>,
request_id: Option<String>,
},
#[error("provider `{0}` is not configured with a model")]
MissingModel(&'static str),
#[error("invalid request: {0}")]
InvalidRequest(String),
#[error("unsupported operation: {0}")]
Unsupported(String),
#[error("tool `{0}` was requested by the model but is not registered")]
ToolNotFound(String),
#[error("tool `{tool}` failed: {message}")]
ToolFailed {
tool: String,
message: String,
},
#[error("agent exceeded max_steps={0}")]
MaxSteps(usize),
#[error("normalization error: {0}")]
Normalize(String),
#[error("invalid retry policy: {0}")]
InvalidRetryPolicy(String),
#[error("invalid HTTP header value: {0}")]
HeaderValue(#[from] reqwest::header::InvalidHeaderValue),
#[error("invalid HTTP header name: {0}")]
HeaderName(#[from] reqwest::header::InvalidHeaderName),
#[error("protected HTTP header cannot be overridden: {0}")]
ProtectedHeader(String),
#[error("HTTP header `{name}` must be ASCII for interoperability")]
NonAsciiHeaderValue {
name: String,
},
#[error("{protocol} extra body field `{field}` cannot override a canonical SDK field")]
ReservedExtraBodyField {
protocol: &'static str,
field: String,
},
#[error("{protocol} extra query parameter `{parameter}` is reserved by the endpoint")]
ReservedExtraQuery {
protocol: &'static str,
parameter: String,
},
#[error("invalid endpoint: {0}")]
InvalidEndpoint(String),
#[error("invalid provider profile: {0}")]
InvalidProfile(String),
}
struct RedactedBody(usize);
impl From<reqwest::Error> for Error {
fn from(error: reqwest::Error) -> Self {
Self::Http(error.without_url())
}
}
impl fmt::Debug for RedactedBody {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "<redacted {} bytes>", self.0)
}
}
impl fmt::Debug for Error {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::MissingApiKey(value) => {
formatter.debug_tuple("MissingApiKey").field(value).finish()
}
Self::Http(error) => formatter
.debug_struct("Http")
.field("kind", &classify_reqwest_error(error))
.finish(),
Self::Cancelled => formatter.write_str("Cancelled"),
Self::Timeout(message) => formatter.debug_tuple("Timeout").field(message).finish(),
Self::Json(error) => formatter.debug_tuple("Json").field(error).finish(),
Self::StreamProtocol(value) => formatter
.debug_tuple("StreamProtocol")
.field(value)
.finish(),
Self::ProviderStream(value) => formatter
.debug_tuple("ProviderStream")
.field(&RedactedBody(value.len()))
.finish(),
Self::ResponseLimit { resource, limit } => formatter
.debug_struct("ResponseLimit")
.field("resource", resource)
.field("limit", limit)
.finish(),
Self::Api {
provider,
status,
body,
retry_after,
retry_source,
request_id,
} => formatter
.debug_struct("Api")
.field("provider", provider)
.field("status", status)
.field("body", &RedactedBody(body.len()))
.field("retry_after", retry_after)
.field("retry_source", retry_source)
.field("request_id", request_id)
.finish(),
Self::MissingModel(value) => {
formatter.debug_tuple("MissingModel").field(value).finish()
}
Self::InvalidRequest(value) => formatter
.debug_tuple("InvalidRequest")
.field(value)
.finish(),
Self::Unsupported(value) => formatter.debug_tuple("Unsupported").field(value).finish(),
Self::ToolNotFound(value) => {
formatter.debug_tuple("ToolNotFound").field(value).finish()
}
Self::ToolFailed { tool, message } => formatter
.debug_struct("ToolFailed")
.field("tool", tool)
.field("message", message)
.finish(),
Self::MaxSteps(value) => formatter.debug_tuple("MaxSteps").field(value).finish(),
Self::Normalize(value) => formatter.debug_tuple("Normalize").field(value).finish(),
Self::InvalidRetryPolicy(value) => formatter
.debug_tuple("InvalidRetryPolicy")
.field(value)
.finish(),
Self::HeaderValue(error) => formatter.debug_tuple("HeaderValue").field(error).finish(),
Self::HeaderName(error) => formatter.debug_tuple("HeaderName").field(error).finish(),
Self::ProtectedHeader(value) => formatter
.debug_tuple("ProtectedHeader")
.field(value)
.finish(),
Self::NonAsciiHeaderValue { name } => formatter
.debug_struct("NonAsciiHeaderValue")
.field("name", name)
.finish(),
Self::ReservedExtraBodyField { protocol, field } => formatter
.debug_struct("ReservedExtraBodyField")
.field("protocol", protocol)
.field("field", field)
.finish(),
Self::ReservedExtraQuery {
protocol,
parameter,
} => formatter
.debug_struct("ReservedExtraQuery")
.field("protocol", protocol)
.field("parameter", parameter)
.finish(),
Self::InvalidEndpoint(value) => formatter
.debug_tuple("InvalidEndpoint")
.field(value)
.finish(),
Self::InvalidProfile(value) => formatter
.debug_tuple("InvalidProfile")
.field(value)
.finish(),
}
}
}
impl Error {
pub fn kind(&self) -> ErrorKind {
match self {
Self::MissingApiKey(_) => ErrorKind::Authentication,
Self::Http(error) => classify_reqwest_error(error),
Self::Cancelled => ErrorKind::Cancelled,
Self::Timeout(_) => ErrorKind::Timeout,
Self::Json(_) => ErrorKind::Decode,
Self::StreamProtocol(_) => ErrorKind::StreamProtocol,
Self::ProviderStream(value) => classify_provider_stream(value),
Self::ResponseLimit { .. } => ErrorKind::Decode,
Self::Api { status, body, .. } => classify_api_error(*status, body),
Self::MissingModel(_) => ErrorKind::Configuration,
Self::InvalidRequest(_) => ErrorKind::InvalidRequest,
Self::Unsupported(_) => ErrorKind::Unsupported,
Self::ToolNotFound(_) | Self::ToolFailed { .. } => ErrorKind::Tool,
Self::MaxSteps(_) => ErrorKind::MaxSteps,
Self::Normalize(_) => ErrorKind::Normalization,
Self::InvalidRetryPolicy(_)
| Self::HeaderValue(_)
| Self::HeaderName(_)
| Self::ProtectedHeader(_)
| Self::NonAsciiHeaderValue { .. }
| Self::ReservedExtraBodyField { .. }
| Self::ReservedExtraQuery { .. }
| Self::InvalidEndpoint(_)
| Self::InvalidProfile(_) => ErrorKind::Configuration,
}
}
pub fn status(&self) -> Option<u16> {
match self {
Self::Api { status, .. } => Some(*status),
_ => None,
}
}
pub fn provider(&self) -> Option<&str> {
match self {
Self::Api { provider, .. } => Some(provider),
_ => None,
}
}
pub fn request_id(&self) -> Option<&str> {
match self {
Self::Api { request_id, .. } => request_id.as_deref(),
_ => None,
}
}
pub fn raw_body(&self) -> Option<&str> {
match self {
Self::Api { body, .. } | Self::ProviderStream(body) => Some(body),
_ => None,
}
}
pub fn body_bytes(&self) -> Option<usize> {
match self {
Self::Api { body, .. } | Self::ProviderStream(body) => Some(body.len()),
_ => None,
}
}
pub fn provider_error(&self) -> Option<ProviderErrorInfo> {
match self {
Self::Api { body, .. } | Self::ProviderStream(body) => Some(parse_provider_error(body)),
_ => None,
}
}
pub fn retry_after(&self) -> Option<Duration> {
match self {
Self::Api { retry_after, .. } => *retry_after,
_ => None,
}
}
pub fn retry_source(&self) -> Option<RetrySource> {
match self {
Self::Api { retry_source, .. } => *retry_source,
_ => None,
}
}
pub fn is_retryable(&self) -> bool {
self.kind().is_retryable()
}
}
fn parse_provider_error(body: &str) -> ProviderErrorInfo {
let Ok(value) = serde_json::from_str::<serde_json::Value>(body) else {
return ProviderErrorInfo {
message_bytes: Some(body.len()),
..ProviderErrorInfo::default()
};
};
let top = value.as_object();
let nested = top
.and_then(|object| object.get("error"))
.and_then(serde_json::Value::as_object);
let error_value = top.and_then(|object| object.get("error"));
let code = nested
.and_then(|object| object.get("code"))
.or_else(|| top.and_then(|object| object.get("error_code")))
.or_else(|| top.and_then(|object| object.get("code")))
.and_then(provider_token);
let error_type = nested
.and_then(|object| object.get("type"))
.or_else(|| top.and_then(|object| object.get("type")))
.and_then(provider_token);
let status = nested
.and_then(|object| object.get("status"))
.or_else(|| top.and_then(|object| object.get("status")))
.and_then(provider_token);
let message = nested
.and_then(|object| object.get("message"))
.or_else(|| top.and_then(|object| object.get("message")))
.or_else(|| top.and_then(|object| object.get("error_msg")))
.or_else(|| top.and_then(|object| object.get("error_description")))
.or(error_value);
let message_bytes = match message {
Some(serde_json::Value::String(message)) => Some(message.len()),
_ => None,
};
let details_count = nested
.and_then(|object| object.get("details"))
.or_else(|| top.and_then(|object| object.get("details")))
.and_then(serde_json::Value::as_array)
.map_or(0, Vec::len);
ProviderErrorInfo {
code,
error_type,
status,
message_bytes,
details_count,
}
}
fn provider_token(value: &serde_json::Value) -> Option<String> {
let token = match value {
serde_json::Value::String(token) => token.trim(),
serde_json::Value::Number(token) => return Some(token.to_string()),
_ => return None,
};
if token.is_empty() || token.len() > 96 {
return None;
}
if !token.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.' | b':' | b'/')
}) {
return None;
}
Some(token.to_string())
}
const MESSAGE_SCAN_LIMIT: usize = 8 * 1024;
const CONTEXT_LENGTH_MARKERS: &[&str] = &[
"context_length_exceeded",
"context length",
"context window",
"context limit",
"context too long",
"prompt is too long",
"too many tokens",
"reduce the length",
"input length",
];
const CONTENT_FILTER_MARKERS: &[&str] = &[
"content_filter",
"content filter",
"content policy",
"content safety",
"safety policy",
"policy violation",
"filtered due to",
];
fn classify_api_error(status: u16, body: &str) -> ErrorKind {
let parsed = serde_json::from_str::<serde_json::Value>(body).ok();
if let Some(kind) = classify_error_tokens(parsed.as_ref()) {
return kind;
}
if matches!(classify_status(status), ErrorKind::InvalidRequest)
&& let Some(kind) = classify_error_message(parsed.as_ref(), body)
{
return kind;
}
classify_status(status)
}
fn classify_provider_stream(payload: &str) -> ErrorKind {
let parsed = serde_json::from_str::<serde_json::Value>(payload).ok();
classify_error_tokens(parsed.as_ref())
.or_else(|| classify_error_message(parsed.as_ref(), payload))
.unwrap_or(ErrorKind::ProviderInternal)
}
fn classify_error_tokens(parsed: Option<&serde_json::Value>) -> Option<ErrorKind> {
let value = parsed?;
error_tokens(value)
.iter()
.find_map(|token| classify_token(token))
}
fn classify_error_message(parsed: Option<&serde_json::Value>, payload: &str) -> Option<ErrorKind> {
let text = match parsed {
Some(value) => provider_message_text(value)?,
None => scan_prefix(payload),
};
let lower = text.to_ascii_lowercase();
if CONTEXT_LENGTH_MARKERS
.iter()
.any(|marker| lower.contains(marker))
{
return Some(ErrorKind::ContextLengthExceeded);
}
if CONTENT_FILTER_MARKERS
.iter()
.any(|marker| lower.contains(marker))
{
return Some(ErrorKind::ContentFiltered);
}
None
}
fn classify_token(token: &str) -> Option<ErrorKind> {
match token.to_ascii_lowercase().as_str() {
"context_length_exceeded"
| "context_length_exceeded_error"
| "context_too_long"
| "prompt_too_long"
| "max_tokens_exceeded" => Some(ErrorKind::ContextLengthExceeded),
"content_filter"
| "content_filtered"
| "content_policy_violation"
| "safety"
| "safety_blocked" => Some(ErrorKind::ContentFiltered),
_ => None,
}
}
fn error_tokens(value: &serde_json::Value) -> Vec<String> {
const FIELDS: [&str; 4] = ["code", "error_code", "type", "status"];
let mut tokens = Vec::new();
for node in error_nodes(value) {
for field in FIELDS {
if let Some(token) = node.get(field).and_then(provider_token) {
tokens.push(token);
}
}
}
tokens
}
fn error_nodes(value: &serde_json::Value) -> Vec<&serde_json::Value> {
let mut nodes = Vec::new();
if value.is_object() || value.is_string() {
nodes.push(value);
}
for path in [
["error"].as_slice(),
["error", "error"].as_slice(),
["response", "error"].as_slice(),
] {
let mut node = value;
for key in path {
node = match node.get(key) {
Some(next) => next,
None => break,
};
}
if (node.is_object() || node.is_string()) && !nodes.contains(&node) {
nodes.push(node);
}
}
nodes
}
fn provider_message_text(value: &serde_json::Value) -> Option<String> {
for node in error_nodes(value) {
if let Some(text) = node.as_str() {
return Some(scan_prefix(text));
}
for field in [
"message",
"error_message",
"error_msg",
"error_description",
"reason",
] {
if let Some(text) = node.get(field).and_then(serde_json::Value::as_str) {
return Some(scan_prefix(text));
}
}
}
None
}
fn scan_prefix(text: &str) -> String {
let mut end = text.len().min(MESSAGE_SCAN_LIMIT);
while !text.is_char_boundary(end) {
end -= 1;
}
text[..end].to_string()
}
fn classify_status(status: u16) -> ErrorKind {
match status {
401 => ErrorKind::Authentication,
403 => ErrorKind::PermissionDenied,
404 => ErrorKind::NotFound,
408 => ErrorKind::Timeout,
425 => ErrorKind::Overloaded,
429 => ErrorKind::RateLimited,
400 | 409 | 413 | 415 | 416 | 422 => ErrorKind::InvalidRequest,
500..=599 => ErrorKind::ProviderInternal,
_ => ErrorKind::Unknown,
}
}
fn classify_reqwest_error(error: &reqwest::Error) -> ErrorKind {
if error.is_timeout() {
ErrorKind::Timeout
} else if error.is_connect() || error.is_request() || error.is_body() {
ErrorKind::Connection
} else if error.is_decode() {
ErrorKind::Decode
} else if error.is_builder() {
ErrorKind::InvalidRequest
} else {
ErrorKind::Unknown
}
}