1use 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case")]
35pub enum ErrorKind {
36 Http,
41 Json,
43 Url,
45 Request,
47 Response,
49 Provider,
51 ProviderResponse,
55 Tool(ToolErrorKind),
57 Internal,
59 Cancelled,
61 Timeout,
63 HandlerUnavailable,
66 Divergence,
69 Denied,
72 Other,
74}
75
76impl ErrorKind {
77 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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
108pub struct ErrorReport {
109 pub kind: ErrorKind,
111 pub retryable: bool,
113 pub message: String,
115 pub code: Option<String>,
120 pub http_status: Option<u16>,
122 pub refusal: bool,
124 pub source_chain: Vec<String>,
126 #[serde(default, skip_serializing_if = "Option::is_none")]
129 pub request_id: Option<String>,
130 #[serde(default, skip_serializing_if = "Option::is_none")]
133 pub provider_response: Option<crate::provider_response::ProviderResponseError>,
134}
135
136impl ErrorReport {
137 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 pub fn with_retryable(mut self, retryable: bool) -> Self {
154 self.retryable = retryable;
155 self
156 }
157
158 pub fn with_code(mut self, code: impl Into<String>) -> Self {
160 self.code = Some(code.into());
161 self
162 }
163
164 pub fn with_http_status(mut self, status: u16) -> Self {
166 self.http_status = Some(status);
167 self
168 }
169
170 pub fn refused(mut self) -> Self {
172 self.refusal = true;
173 self
174 }
175
176 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 pub const fn is_retryable(&self) -> bool {
184 self.retryable
185 }
186}
187
188impl ErrorReport {
189 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 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 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 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 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
230pub(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#[cfg(not(target_family = "wasm"))]
243pub type SharedError = Arc<dyn std::error::Error + Send + Sync + 'static>;
244
245#[cfg(target_family = "wasm")]
248pub type SharedError = Arc<dyn std::error::Error + 'static>;
249
250#[non_exhaustive]
278#[derive(Debug, Clone)]
279pub enum ProviderError {
280 Http(Arc<http_client::Error>),
284 Json(Arc<serde_json::Error>),
286 Url(url::ParseError),
288 Request(SharedError),
290 Response(String),
292 Provider(String),
297 ProviderResponse(ProviderResponseError),
300 InvalidAuthentication(ProviderResponseError),
302 CacheExpired {
306 name: String,
308 response: ProviderResponseError,
310 },
311 MismatchedDimensions {
315 provider: String,
317 requested: usize,
319 returned: usize,
321 },
322 Relayed(Box<ErrorReport>),
325 Truncated,
328 Stalled(std::time::Duration),
333 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
381impl 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 pub fn request(reason: impl Into<BoxError>) -> Self {
403 Self::Request(Arc::from(reason.into()))
404 }
405
406 pub fn from_http_response(status: http::StatusCode, body: impl Into<String>) -> Self {
409 Self::ProviderResponse(ProviderResponseError::new(status, body))
410 }
411
412 pub fn from_provider_body(body: impl Into<String>) -> Self {
415 Self::ProviderResponse(ProviderResponseError::from_body(body))
416 }
417
418 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 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 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 Self::Truncated => true,
464 Self::Stalled(_) => true,
466 _ => false,
467 }
468 }
469
470 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 pub fn provider_response_body(&self) -> Option<&str> {
484 self.provider_response()
485 .map(|response| response.body.as_str())
486 }
487
488 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 pub fn provider_response_status(&self) -> Option<http::StatusCode> {
496 self.provider_response()
497 .and_then(|response| response.status)
498 }
499
500 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 pub fn provider_response_headers(&self) -> Option<&http::HeaderMap> {
519 self.provider_response()
520 .and_then(|response| response.headers.as_ref())
521 }
522
523 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 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 pub fn with_provider_status(self, status: Option<http::StatusCode>) -> Self {
543 self.map_response(|response| response.with_status(status))
544 }
545
546 pub fn with_provider_code(self, code: Option<String>) -> Self {
549 self.map_response(|response| response.with_code(code))
550 }
551
552 pub fn with_transient(self, transient: Option<bool>) -> Self {
555 self.map_response(|response| response.with_transient(transient))
556 }
557
558 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 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#[non_exhaustive]
620#[derive(Debug, thiserror::Error)]
621#[error(transparent)]
622pub struct EncodeError(ProviderError);
623
624impl EncodeError {
625 pub fn request(reason: impl Into<BoxError>) -> Self {
627 Self(ProviderError::request(reason))
628 }
629
630 pub fn unsupported(option: UnsupportedOption) -> Self {
632 Self(ProviderError::UnsupportedOption(option))
633 }
634
635 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 pub fn report(&self) -> ErrorReport {
706 ErrorReport::from(self)
707 }
708}
709
710impl ToolExecutionError {
711 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
744impl 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 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
852const _: 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;