Skip to main content

rig_core/
error.rs

1//! The provider error type, serializable error reports, and shared retry
2//! classifications for the effect protocol. Reports preserve classifications,
3//! available provider metadata, and textual source chains.
4//!
5//! ```
6//! use rig_core::error::{ErrorKind, ProviderError};
7//!
8//! let error = ProviderError::from_http_response(http::StatusCode::TOO_MANY_REQUESTS, "slow down");
9//! assert!(error.is_retryable());
10//! assert_eq!(error.report().kind, ErrorKind::ProviderResponse);
11//! ```
12
13use std::fmt;
14use std::sync::Arc;
15
16use serde::{Deserialize, Serialize};
17
18use crate::{
19    completion::UnsupportedOption,
20    http_client,
21    provider_response::ProviderResponseError,
22    tool::{ToolErrorKind, ToolExecutionError},
23    vector_store::VectorStoreError,
24};
25
26mod rate_limits;
27mod retry;
28
29pub(crate) use rate_limits::rfc3339;
30pub use rate_limits::{Allowance, RateLimits};
31
32/// Normalized classification of an [`ErrorReport`].
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case")]
35pub enum ErrorKind {
36    /// A transport failure that produced no provider reply: a reset
37    /// connection, a timeout, a protocol error, an unreadable response. It
38    /// never carries a status; a reply the server made, whatever its status,
39    /// is [`Self::ProviderResponse`].
40    Http,
41    /// JSON serialization or deserialization failed.
42    Json,
43    /// A URL could not be parsed.
44    Url,
45    /// The request could not be built.
46    Request,
47    /// The response could not be parsed.
48    Response,
49    /// The provider reported a failure without a preserved raw response.
50    Provider,
51    /// The provider replied and its raw response was preserved: a non-2xx
52    /// status with a body, a 2xx error envelope, or a non-HTTP transport's
53    /// error payload. Status, body, request id and headers are on the report.
54    ProviderResponse,
55    /// A tool failed; the inner kind is the tool's own classification.
56    Tool(ToolErrorKind),
57    /// An internal invariant was violated.
58    Internal,
59    /// The operation was cancelled.
60    Cancelled,
61    /// The operation exceeded its deadline.
62    Timeout,
63    /// No handler serves the requested key and effect family.
64    /// The message identifies the key.
65    HandlerUnavailable,
66    /// Replay requested a different effect or exhausted the log.
67    /// The run fails without retry rather than inventing a recorded answer.
68    Divergence,
69    /// Policy denied dispatch before handler execution. Not retryable under
70    /// the same policy; distinct from program cancellation.
71    Denied,
72    /// Anything else.
73    Other,
74}
75
76impl ErrorKind {
77    /// Stable snake-case classification code, excluding variant payloads.
78    pub fn code(&self) -> &'static str {
79        match self {
80            Self::Http => "http",
81            Self::Json => "json",
82            Self::Url => "url",
83            Self::Request => "request",
84            Self::Response => "response",
85            Self::Provider => "provider",
86            Self::ProviderResponse => "provider_response",
87            Self::Tool(_) => "tool",
88            Self::Internal => "internal",
89            Self::Cancelled => "cancelled",
90            Self::Timeout => "timeout",
91            Self::HandlerUnavailable => "handler_unavailable",
92            Self::Divergence => "divergence",
93            Self::Denied => "denied",
94            Self::Other => "other",
95        }
96    }
97}
98
99/// A serde-able error crossing a wire boundary.
100///
101/// Field semantics:
102/// - `retryable` is the one policy signal; it is decided at conversion time
103///   from the source's own classification (see [`retryable_status`]).
104/// - `message` is the source's `Display`; `source_chain` is the `Display` of
105///   each `source()` link, outermost first, excluding `message` itself.
106/// - `code`, `http_status`, `refusal` are copied when the source had them.
107#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
108pub struct ErrorReport {
109    /// Normalized classification.
110    pub kind: ErrorKind,
111    /// Whether the same operation may reasonably be retried.
112    pub retryable: bool,
113    /// Human-readable description (the source's `Display`).
114    pub message: String,
115    /// A provider- or tool-specific machine code, when one was reported:
116    /// for a provider's reply, the transport's own code when it gave one
117    /// apart from the body, else the code the body names
118    /// ([`ProviderResponseError::machine_code`]).
119    pub code: Option<String>,
120    /// The HTTP status, when the failure had one.
121    pub http_status: Option<u16>,
122    /// The failure was an intentional refusal rather than a fault.
123    pub refusal: bool,
124    /// `Display` of each `source()` link, outermost first.
125    pub source_chain: Vec<String>,
126    /// The provider's request id, when the failure had a response that
127    /// carried one.
128    #[serde(default, skip_serializing_if = "Option::is_none")]
129    pub request_id: Option<String>,
130    /// Preserved provider failure response, including available status, body,
131    /// headers, and request ID.
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub provider_response: Option<crate::provider_response::ProviderResponseError>,
134}
135
136impl ErrorReport {
137    /// Build a report of `kind` with `message` and no other metadata.
138    pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
139        Self {
140            kind,
141            retryable: false,
142            message: message.into(),
143            code: None,
144            http_status: None,
145            refusal: false,
146            source_chain: Vec::new(),
147            request_id: None,
148            provider_response: None,
149        }
150    }
151
152    /// Set `retryable`.
153    pub fn with_retryable(mut self, retryable: bool) -> Self {
154        self.retryable = retryable;
155        self
156    }
157
158    /// Set the machine code.
159    pub fn with_code(mut self, code: impl Into<String>) -> Self {
160        self.code = Some(code.into());
161        self
162    }
163
164    /// Set the HTTP status.
165    pub fn with_http_status(mut self, status: u16) -> Self {
166        self.http_status = Some(status);
167        self
168    }
169
170    /// Mark the report as an intentional refusal.
171    pub fn refused(mut self) -> Self {
172        self.refusal = true;
173        self
174    }
175
176    /// Attach the provider's request id.
177    pub fn with_request_id(mut self, request_id: impl Into<String>) -> Self {
178        self.request_id = Some(request_id.into());
179        self
180    }
181
182    /// Whether the same operation may reasonably be retried.
183    pub const fn is_retryable(&self) -> bool {
184        self.retryable
185    }
186}
187
188impl ErrorReport {
189    /// The provider response body preserved on this report, if any.
190    pub fn provider_response_body(&self) -> Option<&str> {
191        self.provider_response
192            .as_ref()
193            .map(|response| response.body.as_str())
194    }
195
196    /// The preserved provider response body parsed as JSON, when present.
197    pub fn provider_response_json(&self) -> Result<Option<serde_json::Value>, serde_json::Error> {
198        crate::provider_response::json(self.provider_response_body())
199    }
200
201    /// The preserved provider response headers, if any.
202    pub fn provider_response_headers(&self) -> Option<&http::HeaderMap> {
203        self.provider_response
204            .as_ref()
205            .and_then(|response| response.headers.as_ref())
206    }
207
208    /// The HTTP status this report carries, as a status code.
209    pub fn provider_response_status(&self) -> Option<http::StatusCode> {
210        self.http_status
211            .and_then(|status| http::StatusCode::from_u16(status).ok())
212    }
213
214    /// The provider's transport request id, if the failure carried one.
215    pub fn provider_request_id(&self) -> Option<&str> {
216        self.request_id.as_deref()
217    }
218}
219
220impl fmt::Display for ErrorReport {
221    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
222        f.write_str(&self.message)
223    }
224}
225
226impl std::error::Error for ErrorReport {}
227
228pub use crate::http_client::retryable_status;
229
230/// Collect the `Display` of each `source()` link below `error`, outermost
231/// first.
232pub(crate) fn source_chain(error: &(dyn std::error::Error + 'static)) -> Vec<String> {
233    std::iter::successors(error.source(), |source| source.source())
234        .map(ToString::to_string)
235        .collect()
236}
237
238pub use crate::http_client::BoxError;
239
240/// A request-building failure shared by every clone of the error that holds
241/// it.
242#[cfg(not(target_family = "wasm"))]
243pub type SharedError = Arc<dyn std::error::Error + Send + Sync + 'static>;
244
245/// A request-building failure shared by every clone of the error that holds
246/// it.
247#[cfg(target_family = "wasm")]
248pub type SharedError = Arc<dyn std::error::Error + 'static>;
249
250/// A failed provider operation: completion, embedding, reranking,
251/// transcription, image or audio generation, verification, model listing, or
252/// context caching.
253///
254/// The variant is the classification, and each variant maps to one
255/// [`ErrorKind`]. A provider's reply is preserved as a
256/// [`ProviderResponseError`] with its status, body, headers, and request ID;
257/// read it through [`Self::provider_response`] or the accessors below.
258///
259/// ```
260/// use rig_core::error::ProviderError;
261///
262/// fn log(error: &ProviderError) {
263///     if let Some(status) = error.provider_response_status() {
264///         // Error envelopes can arrive with successful HTTP statuses.
265///         eprintln!("provider returned HTTP {status}");
266///     }
267///     match error.provider_response_json() {
268///         Ok(Some(json)) => eprintln!("provider error payload: {json}"),
269///         Ok(None) => eprintln!("no provider response body: {error}"),
270///         Err(_) => eprintln!("non-JSON body: {:?}", error.provider_response_body()),
271///     }
272/// }
273/// ```
274///
275/// Errors are `Clone`: sources are shared, so a stream that already yielded
276/// an error can hand the same error to a later caller.
277#[non_exhaustive]
278#[derive(Debug, Clone)]
279pub enum ProviderError {
280    /// A transport failure that produced no provider reply: a reset
281    /// connection, a timeout, an unreadable response. A reply the server
282    /// made is [`Self::ProviderResponse`].
283    Http(Arc<http_client::Error>),
284    /// JSON serialization or deserialization failed.
285    Json(Arc<serde_json::Error>),
286    /// A URL could not be parsed.
287    Url(url::ParseError),
288    /// The request could not be built.
289    Request(SharedError),
290    /// The reply decoded but does not answer the request.
291    Response(String),
292    /// The provider reported a failure without a preserved reply: a Rig
293    /// diagnostic, never classified as retryable. A provider's own error
294    /// payload belongs in [`Self::ProviderResponse`], whose envelope decides
295    /// its code and retry verdict; never put provider JSON here.
296    Provider(String),
297    /// The provider's reply, preserved: a non-success status with its body, a
298    /// 2xx error envelope, or a non-HTTP transport's error payload.
299    ProviderResponse(ProviderResponseError),
300    /// The provider rejected the configured credentials with 401 or 403.
301    InvalidAuthentication(ProviderResponseError),
302    /// A request for an existing context-cache handle answered 403 or 404.
303    /// The reply's body is the provider's explanation, which can name a
304    /// cause other than expiry, such as a credential or quota failure.
305    CacheExpired {
306        /// The cache handle the request named.
307        name: String,
308        /// The provider's reply.
309        response: ProviderResponseError,
310    },
311    /// The provider returned vectors of a width other than the one the caller
312    /// declared through an embedding wire's `ndims` argument. Raised only
313    /// when the width was set explicitly.
314    MismatchedDimensions {
315        /// Provider whose response disagreed with the declared width.
316        provider: String,
317        /// Width the caller declared.
318        requested: usize,
319        /// Width the provider actually returned.
320        returned: usize,
321    },
322    /// A failure a relay delivered as its report, such as a relayed
323    /// stream. It reports as the relayed report, unchanged.
324    Relayed(Box<ErrorReport>),
325    /// The reply stopped before the provider ended it: its frames ran out,
326    /// or the runtime stopped, without the provider's end.
327    Truncated,
328    /// A streamed reply sent no frame for this long, from when it was sent
329    /// to its first frame or between two, and was dropped. Bytes that are
330    /// no frame, such as an event stream's comments, do not count.
331    /// Retryable.
332    Stalled(std::time::Duration),
333    /// A [`GenerationOptions`](crate::completion::GenerationOptions) field
334    /// the wire or model cannot honour, under
335    /// [`OnUnsupported::Error`](crate::completion::OnUnsupported::Error).
336    UnsupportedOption(UnsupportedOption),
337}
338
339impl fmt::Display for ProviderError {
340    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
341        match self {
342            Self::Http(error) => write!(f, "HttpError: {error}"),
343            Self::Json(error) => write!(f, "JsonError: {error}"),
344            Self::Url(error) => write!(f, "UrlError: {error}"),
345            Self::Request(error) => write!(f, "RequestError: {error}"),
346            Self::Response(message) => write!(f, "ResponseError: {message}"),
347            Self::Provider(message) => write!(f, "ProviderError: {message}"),
348            Self::ProviderResponse(response) => write!(f, "ProviderResponseError: {response}"),
349            Self::InvalidAuthentication(response) => {
350                write!(f, "invalid authentication: {response}")
351            }
352            Self::CacheExpired { name, response } => write!(
353                f,
354                "cached content `{name}` is expired or was deleted: {}",
355                response.body
356            ),
357            Self::MismatchedDimensions {
358                provider,
359                requested,
360                returned,
361            } => write!(
362                f,
363                "{provider} embedding response returned {returned}-dimension vectors, but the \
364                 model was created with {requested} dimensions; this provider does not resize \
365                 embeddings"
366            ),
367            Self::Relayed(report) => f.write_str(&report.message),
368            Self::Truncated => {
369                f.write_str("ResponseError: the reply ended before the provider ended it")
370            }
371            Self::Stalled(idle) => write!(
372                f,
373                "TimeoutError: the streamed reply sent no event for {}s",
374                idle.as_secs_f64()
375            ),
376            Self::UnsupportedOption(option) => write!(f, "RequestError: {option}"),
377        }
378    }
379}
380
381/// The source is the shared error itself, not its `Arc`, so callers can
382/// downcast it.
383impl std::error::Error for ProviderError {
384    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
385        match self {
386            Self::Json(error) => Some(&**error),
387            Self::Url(error) => Some(error),
388            Self::Request(error) => Some(&**error),
389            _ => None,
390        }
391    }
392}
393
394impl From<url::ParseError> for ProviderError {
395    fn from(error: url::ParseError) -> Self {
396        Self::Url(error)
397    }
398}
399
400impl ProviderError {
401    /// A request that could not be built, for the given reason.
402    pub fn request(reason: impl Into<BoxError>) -> Self {
403        Self::Request(Arc::from(reason.into()))
404    }
405
406    /// Preserves the status and verbatim body as [`Self::ProviderResponse`],
407    /// including error envelopes returned with 2xx statuses.
408    pub fn from_http_response(status: http::StatusCode, body: impl Into<String>) -> Self {
409        Self::ProviderResponse(ProviderResponseError::new(status, body))
410    }
411
412    /// Preserves a verbatim provider error body with no HTTP status as
413    /// [`Self::ProviderResponse`] (see [`ProviderResponseError::from_body`]).
414    pub fn from_provider_body(body: impl Into<String>) -> Self {
415        Self::ProviderResponse(ProviderResponseError::from_body(body))
416    }
417
418    /// Converts a non-success reply the transport reported as an error to
419    /// [`Self::ProviderResponse`], keeping its status, body, and headers.
420    /// Other transport errors become [`Self::Http`].
421    pub fn from_transport_error(error: http_client::Error) -> Self {
422        match error {
423            http_client::Error::InvalidStatusCodeWithDetails {
424                status,
425                body,
426                headers,
427            } => Self::from_http_response(status, body).with_response_headers(Some(headers)),
428            other => Self::Http(Arc::new(other)),
429        }
430    }
431
432    /// The classification this error reports as.
433    pub fn kind(&self) -> ErrorKind {
434        match self {
435            Self::Http(_) => ErrorKind::Http,
436            Self::Json(_) => ErrorKind::Json,
437            Self::Url(_) => ErrorKind::Url,
438            Self::Request(_) | Self::UnsupportedOption(_) => ErrorKind::Request,
439            Self::Response(_) | Self::MismatchedDimensions { .. } | Self::Truncated => {
440                ErrorKind::Response
441            }
442            Self::Provider(_) => ErrorKind::Provider,
443            Self::Stalled(_) => ErrorKind::Timeout,
444            Self::ProviderResponse(_)
445            | Self::InvalidAuthentication(_)
446            | Self::CacheExpired { .. } => ErrorKind::ProviderResponse,
447            Self::Relayed(report) => report.kind,
448        }
449    }
450
451    /// Classifies transport failures with
452    /// [`http_client::Error::is_transient`] and
453    /// preserved replies with [`ProviderResponseError::is_retryable`]; a
454    /// truncated or stalled reply is retryable. Every other failure, rejected
455    /// credentials and expired caches included, is not retryable.
456    pub fn is_retryable(&self) -> bool {
457        match self {
458            Self::Http(error) => error.is_transient(),
459            Self::ProviderResponse(response) => response.is_retryable(),
460            Self::Relayed(report) => report.retryable,
461            // A reply cut short, by its transport or its runtime, may end on
462            // the next attempt.
463            Self::Truncated => true,
464            // A stalled stream is dropped, so the next attempt starts afresh.
465            Self::Stalled(_) => true,
466            _ => false,
467        }
468    }
469
470    /// The provider's preserved reply, when this error carries one.
471    pub fn provider_response(&self) -> Option<&ProviderResponseError> {
472        match self {
473            Self::ProviderResponse(response)
474            | Self::InvalidAuthentication(response)
475            | Self::CacheExpired { response, .. } => Some(response),
476            Self::Relayed(report) => report.provider_response.as_ref(),
477            _ => None,
478        }
479    }
480
481    /// The preserved reply's body. An empty body returns `Some("")`, while
482    /// [`Self::provider_response_json`] maps it to `Ok(None)`.
483    pub fn provider_response_body(&self) -> Option<&str> {
484        self.provider_response()
485            .map(|response| response.body.as_str())
486    }
487
488    /// Parses the preserved reply's body as JSON: `Ok(None)` when there is no
489    /// body or it is empty, `Err` when it is not valid JSON.
490    pub fn provider_response_json(&self) -> Result<Option<serde_json::Value>, serde_json::Error> {
491        crate::provider_response::json(self.provider_response_body())
492    }
493
494    /// The preserved reply's HTTP status. It may be 2xx for an error envelope.
495    pub fn provider_response_status(&self) -> Option<http::StatusCode> {
496        self.provider_response()
497            .and_then(|response| response.status)
498    }
499
500    /// The provider's transport request ID, when the reply carried one.
501    pub fn provider_request_id(&self) -> Option<&str> {
502        self.provider_response()
503            .and_then(|response| response.provider_request_id.as_deref())
504    }
505
506    /// The preserved reply's headers. `None` means not captured, as for
507    /// non-HTTP transports and replies built from only a status and body.
508    /// For the wait a provider asked for, use
509    /// [`ErrorReport::retry_after`], which reads every form it sends:
510    ///
511    /// ```
512    /// # use rig_core::error::ProviderError;
513    /// # use std::time::{Duration, SystemTime};
514    /// fn backoff(error: &ProviderError) -> Option<Duration> {
515    ///     error.report().retry_after(SystemTime::now())
516    /// }
517    /// ```
518    pub fn provider_response_headers(&self) -> Option<&http::HeaderMap> {
519        self.provider_response()
520            .and_then(|response| response.headers.as_ref())
521    }
522
523    /// Fills an absent request ID on the preserved reply, ignoring empty
524    /// strings.
525    pub fn with_provider_request_id(self, request_id: Option<String>) -> Self {
526        self.map_response(|response| match response.provider_request_id {
527            Some(_) => response,
528            None => response.with_provider_request_id(request_id),
529        })
530    }
531
532    /// Fills absent headers on the preserved reply.
533    pub fn with_response_headers(self, headers: Option<http::HeaderMap>) -> Self {
534        self.map_response(|response| match (&response.headers, headers) {
535            (None, Some(headers)) => response.with_headers(Some(headers)),
536            _ => response,
537        })
538    }
539
540    /// Attaches the HTTP status a transport reported beside a reply preserved
541    /// without one, so it classifies by status. A captured status is kept.
542    pub fn with_provider_status(self, status: Option<http::StatusCode>) -> Self {
543        self.map_response(|response| response.with_status(status))
544    }
545
546    /// Attaches the provider's machine-readable code for the failure, such as
547    /// a gRPC status name or an AWS exception type.
548    pub fn with_provider_code(self, code: Option<String>) -> Self {
549        self.map_response(|response| response.with_code(code))
550    }
551
552    /// Replaces the preserved reply's transport retry verdict, used when its
553    /// status is absent or successful.
554    pub fn with_transient(self, transient: Option<bool>) -> Self {
555        self.map_response(|response| response.with_transient(transient))
556    }
557
558    /// The wire form of this error.
559    pub fn report(&self) -> ErrorReport {
560        ErrorReport::from(self)
561    }
562
563    fn map_response(
564        self,
565        map: impl FnOnce(ProviderResponseError) -> ProviderResponseError,
566    ) -> Self {
567        match self {
568            Self::ProviderResponse(response) => Self::ProviderResponse(map(response)),
569            Self::InvalidAuthentication(response) => Self::InvalidAuthentication(map(response)),
570            Self::CacheExpired { name, response } => Self::CacheExpired {
571                name,
572                response: map(response),
573            },
574            // The report restates what it read from the reply it preserves,
575            // so what the map fills reaches both. What it held is kept.
576            Self::Relayed(mut report) => {
577                if let Some(response) = report.provider_response.take() {
578                    let response = map(response);
579                    report.request_id = report
580                        .request_id
581                        .or_else(|| response.provider_request_id.clone());
582                    report.http_status = report
583                        .http_status
584                        .or_else(|| response.status.map(|status| status.as_u16()));
585                    report.code = report.code.or_else(|| response.machine_code());
586                    report.refusal |= response.refusal;
587                    report.provider_response = Some(response);
588                }
589                Self::Relayed(report)
590            }
591            other => other,
592        }
593    }
594}
595
596impl From<serde_json::Error> for ProviderError {
597    fn from(error: serde_json::Error) -> Self {
598        Self::Json(Arc::new(error))
599    }
600}
601
602impl From<BoxError> for ProviderError {
603    fn from(error: BoxError) -> Self {
604        Self::Request(Arc::from(error))
605    }
606}
607
608impl From<http_client::Error> for ProviderError {
609    fn from(error: http_client::Error) -> Self {
610        Self::from_transport_error(error)
611    }
612}
613
614/// A failure to build a provider request, returned by
615/// [`Wire::encode`](crate::wire::Wire::encode). It converts only into
616/// [`ProviderError::Request`] or [`ProviderError::UnsupportedOption`], both
617/// of kind [`ErrorKind::Request`], so every provider classifies its encode
618/// failures alike.
619#[non_exhaustive]
620#[derive(Debug, thiserror::Error)]
621#[error(transparent)]
622pub struct EncodeError(ProviderError);
623
624impl EncodeError {
625    /// A request that could not be built, for the given reason.
626    pub fn request(reason: impl Into<BoxError>) -> Self {
627        Self(ProviderError::request(reason))
628    }
629
630    /// A request that sets an option the wire or model cannot honour.
631    pub fn unsupported(option: UnsupportedOption) -> Self {
632        Self(ProviderError::UnsupportedOption(option))
633    }
634
635    /// The refused option, when this error is a refusal.
636    pub fn unsupported_option(&self) -> Option<&UnsupportedOption> {
637        match &self.0 {
638            ProviderError::UnsupportedOption(option) => Some(option),
639            _ => None,
640        }
641    }
642}
643
644impl From<EncodeError> for ProviderError {
645    fn from(error: EncodeError) -> Self {
646        debug_assert_eq!(error.0.kind(), ErrorKind::Request);
647        error.0
648    }
649}
650
651impl From<http::Error> for EncodeError {
652    fn from(error: http::Error) -> Self {
653        Self::request(error)
654    }
655}
656
657impl From<serde_json::Error> for EncodeError {
658    fn from(error: serde_json::Error) -> Self {
659        Self::request(error)
660    }
661}
662
663impl From<BoxError> for EncodeError {
664    fn from(error: BoxError) -> Self {
665        Self(ProviderError::from(error))
666    }
667}
668
669impl From<http::Error> for ProviderError {
670    fn from(error: http::Error) -> Self {
671        Self::request(error)
672    }
673}
674
675impl From<&ProviderError> for ErrorReport {
676    fn from(error: &ProviderError) -> Self {
677        if let ProviderError::Relayed(report) = error {
678            return (**report).clone();
679        }
680        let response = error.provider_response();
681        ErrorReport {
682            kind: error.kind(),
683            retryable: error.is_retryable(),
684            message: error.to_string(),
685            code: response.and_then(ProviderResponseError::machine_code),
686            http_status: response
687                .and_then(|response| response.status)
688                .map(|status| status.as_u16()),
689            refusal: response.is_some_and(|response| response.refusal),
690            source_chain: source_chain(error),
691            request_id: response.and_then(|response| response.provider_request_id.clone()),
692            provider_response: response.cloned(),
693        }
694    }
695}
696
697impl From<ProviderError> for ErrorReport {
698    fn from(error: ProviderError) -> Self {
699        Self::from(&error)
700    }
701}
702
703impl ToolExecutionError {
704    /// The wire form of this error.
705    pub fn report(&self) -> ErrorReport {
706        ErrorReport::from(self)
707    }
708}
709
710impl ToolExecutionError {
711    /// Whether the tool may reasonably be re-run: the explicit override when
712    /// one was set, else the kind's own default
713    /// ([`ToolErrorKind::default_retryable`]); a kind that leaves it to the
714    /// tool (`None`) is not retryable on the wire.
715    pub fn is_retryable(&self) -> bool {
716        self.retryable()
717            .or_else(|| self.kind().default_retryable())
718            .unwrap_or(false)
719    }
720}
721
722impl From<&ToolExecutionError> for ErrorReport {
723    fn from(error: &ToolExecutionError) -> Self {
724        ErrorReport {
725            kind: ErrorKind::Tool(error.kind()),
726            retryable: error.is_retryable(),
727            message: error.message().to_string(),
728            code: error.code().map(str::to_string),
729            http_status: error.http_status(),
730            refusal: error.is_refusal(),
731            source_chain: source_chain(error),
732            request_id: None,
733            provider_response: None,
734        }
735    }
736}
737
738impl From<ToolExecutionError> for ErrorReport {
739    fn from(error: ToolExecutionError) -> Self {
740        Self::from(&error)
741    }
742}
743
744/// Rebuilds a tool failure from a dispatch report.
745///
746/// An [`ErrorKind::Tool`] report keeps its tool kind; other kinds map to the
747/// closest [`ToolErrorKind`]. Retryability, code, HTTP status, and refusal are
748/// copied, the message is model-visible, and the report is the `source()`.
749impl From<ErrorReport> for ToolExecutionError {
750    fn from(report: ErrorReport) -> Self {
751        let kind = match report.kind {
752            ErrorKind::Tool(kind) => kind,
753            ErrorKind::Timeout => ToolErrorKind::Timeout,
754            ErrorKind::Cancelled => ToolErrorKind::Cancelled,
755            ErrorKind::Denied => ToolErrorKind::PermissionDenied,
756            ErrorKind::HandlerUnavailable => ToolErrorKind::NotFound,
757            ErrorKind::Http => ToolErrorKind::Network,
758            ErrorKind::Provider | ErrorKind::ProviderResponse => ToolErrorKind::Provider,
759            ErrorKind::Json
760            | ErrorKind::Url
761            | ErrorKind::Request
762            | ErrorKind::Response
763            | ErrorKind::Internal
764            | ErrorKind::Divergence
765            | ErrorKind::Other => ToolErrorKind::Other,
766        };
767        let mut error = if report.refusal {
768            ToolExecutionError::refused(report.message.clone())
769        } else {
770            ToolExecutionError::new(kind, report.message.clone())
771        }
772        .with_retryable(report.retryable);
773        if let Some(code) = &report.code {
774            error = error.with_code(code.clone());
775        }
776        if let Some(status) = report.http_status {
777            error = error.with_http_status(status);
778        }
779        error.with_source(report)
780    }
781}
782
783impl From<&VectorStoreError> for ErrorReport {
784    fn from(error: &VectorStoreError) -> Self {
785        let (kind, provider_response) = match error {
786            VectorStoreError::EmbeddingError(inner) => {
787                return Self {
788                    message: error.to_string(),
789                    source_chain: source_chain(error),
790                    ..Self::from(inner)
791                };
792            }
793            VectorStoreError::JsonError(_) => (ErrorKind::Json, None),
794            VectorStoreError::DatastoreError(_) => (ErrorKind::Provider, None),
795            VectorStoreError::FilterError(_) | VectorStoreError::SamplesOutOfRange { .. } => {
796                (ErrorKind::Request, None)
797            }
798            VectorStoreError::MissingIdError(_) => (ErrorKind::Response, None),
799            VectorStoreError::Http(crate::http_client::Error::InvalidStatusCodeWithDetails {
800                status,
801                body,
802                headers,
803            }) => (
804                ErrorKind::ProviderResponse,
805                Some(
806                    crate::provider_response::ProviderResponseError::new(*status, body.clone())
807                        .with_headers(Some(headers.clone())),
808                ),
809            ),
810            VectorStoreError::Http(_) => (ErrorKind::Http, None),
811            // A store's own non-2xx reply: the server answered, so the status
812            // classifies it and its retryability, like any provider reply.
813            VectorStoreError::ExternalAPIError(status, body) => (
814                ErrorKind::ProviderResponse,
815                Some(crate::provider_response::ProviderResponseError::new(
816                    *status,
817                    body.clone(),
818                )),
819            ),
820        };
821        let http_status = provider_response
822            .as_ref()
823            .and_then(|response| response.status.map(|status| status.as_u16()));
824        let retryable = match error {
825            VectorStoreError::Http(inner) => inner.is_transient(),
826            VectorStoreError::ExternalAPIError(..) => retryable_status(http_status),
827            _ => false,
828        };
829        let code = provider_response
830            .as_ref()
831            .and_then(|response| response.machine_code());
832        ErrorReport {
833            kind,
834            retryable,
835            message: error.to_string(),
836            code,
837            http_status,
838            refusal: provider_response.as_ref().is_some_and(|r| r.refusal),
839            source_chain: source_chain(error),
840            request_id: None,
841            provider_response,
842        }
843    }
844}
845
846impl From<VectorStoreError> for ErrorReport {
847    fn from(error: VectorStoreError) -> Self {
848        Self::from(&error)
849    }
850}
851
852// The report is the wire error of the effect protocol: it must cross threads
853// and serialize on every target, browser wasm included.
854const _: fn() = || {
855    fn assert_wire<T: Send + Sync + 'static + Serialize + serde::de::DeserializeOwned>() {}
856    assert_wire::<ErrorReport>();
857    assert_wire::<ErrorKind>();
858};
859
860#[cfg(test)]
861mod encode_tests;
862#[cfg(test)]
863mod tests;