Skip to main content

rig_core/
provider_response.rs

1//! Preserved provider error responses and their machine codes.
2//!
3//! ```
4//! use rig_core::ProviderResponseError;
5//!
6//! let reply = ProviderResponseError::new(http::StatusCode::TOO_MANY_REQUESTS, "slow down");
7//! assert!(reply.is_retryable());
8//! ```
9use http::StatusCode;
10
11/// A raw provider error body with captured transport metadata.
12/// Callers must supply the provider's actual payload, not a generated diagnostic.
13/// Serialization omits headers and route; deserialization restores them as `None`.
14#[derive(Debug, Clone, PartialEq, Eq)]
15pub struct ProviderResponseError {
16    /// HTTP status of the provider response, when it was captured alongside the body.
17    pub status: Option<StatusCode>,
18    /// Raw response body as returned by the provider.
19    pub body: String,
20    /// Transport request ID from response headers or SDK metadata, when captured.
21    pub provider_request_id: Option<String>,
22    /// Captured response headers, including rate-limit metadata. `None` means
23    /// not captured, rather than an empty header set. Omitted during serialization.
24    pub headers: Option<http::HeaderMap>,
25    /// The provider's own machine-readable code for the failure, when the
26    /// transport reported one apart from the body: a gRPC status code name
27    /// (`UNAVAILABLE`), an AWS exception type (`ThrottlingException`).
28    /// `None` when the reply carried only a status and a body.
29    pub code: Option<String>,
30    /// Transport retry hint, used when neither a non-success status nor a
31    /// known provider code decides; refusals are never retryable.
32    pub transient: Option<bool>,
33    /// Whether this error represents a content refusal. Refusals are never
34    /// retryable; refusal content in a successful model answer is separate.
35    pub refusal: bool,
36    /// The provider and request path the reply answered, when the operation
37    /// records them for diagnostics (model listing does). Omitted during
38    /// serialization.
39    pub route: Option<String>,
40}
41
42impl ProviderResponseError {
43    /// Preserve a provider error response captured with its HTTP status.
44    pub fn new(status: StatusCode, body: impl Into<String>) -> Self {
45        let status = Some(status);
46        Self {
47            status,
48            ..Self::without_status(body)
49        }
50    }
51
52    /// Preserve a provider error body that has no HTTP status (gRPC / SDK
53    /// transports).
54    pub fn without_status(body: impl Into<String>) -> Self {
55        Self {
56            status: None,
57            body: body.into(),
58            provider_request_id: None,
59            headers: None,
60            code: None,
61            transient: None,
62            refusal: false,
63            route: None,
64        }
65    }
66
67    /// Preserve a provider error body delivered with no HTTP status of its
68    /// own: an error event inside a stream, or a non-HTTP transport's reply.
69    /// An error envelope that nests an HTTP status as its numeric code
70    /// (`{"error":{"code":503}}`) records it as the status, as the same
71    /// envelope on a non-success response would carry it.
72    pub fn from_body(body: impl Into<String>) -> Self {
73        let mut reply = Self::without_status(body);
74        let status = reply.located(|envelope| envelope.http_status().filter(|_| envelope.nested));
75        reply.status = status.and_then(|status| StatusCode::from_u16(status).ok());
76        reply
77    }
78
79    /// Mark the reply as the provider's verdict on the content: a refusal,
80    /// final, never retried.
81    pub fn with_refusal(mut self, refusal: bool) -> Self {
82        self.refusal = refusal;
83        self
84    }
85
86    /// Attach the HTTP status a transport reported beside a reply that was
87    /// first preserved without one (an SDK that hands back the raw HTTP
88    /// response next to its typed exception). A status already set is kept.
89    pub fn with_status(mut self, status: Option<StatusCode>) -> Self {
90        if self.status.is_none() {
91            self.status = status;
92        }
93        self
94    }
95
96    /// Attach the provider's own machine-readable code for the failure.
97    pub fn with_code(mut self, code: Option<String>) -> Self {
98        self.code = code.filter(|code| !code.is_empty());
99        self
100    }
101
102    /// Replaces the transport retry hint. A refusal, a provider code the
103    /// table knows and a non-success HTTP status each outrank it.
104    pub fn with_transient(mut self, transient: Option<bool>) -> Self {
105        self.transient = transient;
106        self
107    }
108
109    /// Whether the same request may reasonably be sent again, decided in
110    /// this order: a refusal never is; nor is a provider code the one table
111    /// lists as final (the explicit [`Self::code`], else the code the body's
112    /// error envelope names), whatever the status, as a spent quota answers
113    /// 429; a non-success HTTP status decides through
114    /// [`crate::error::retryable_status`]; then any other code the table
115    /// knows; then the `transient` hint; otherwise not.
116    ///
117    /// The body is read on every call, so the same envelope gets the same
118    /// verdict from every decoder and transport, streamed or unary.
119    pub fn is_retryable(&self) -> bool {
120        if self.refusal {
121            return false;
122        }
123        let read = |envelope: Envelope<'_>| Some((envelope.is_final(), envelope.verdict()));
124        let (is_final, known) = match &self.code {
125            Some(code) => read(Envelope::default().named(code)),
126            None => self.located(read),
127        }
128        .unwrap_or_default();
129        if is_final {
130            return false;
131        }
132        if let Some(status) = self.status.filter(|status| !status.is_success()) {
133            return crate::error::retryable_status(Some(status.as_u16()));
134        }
135        known.or(self.transient).unwrap_or(false)
136    }
137
138    /// Returns the explicit code, else the code the body's error envelope
139    /// names: its first nonempty string `code`, `status` or `type`, or else
140    /// its numeric code in decimal (`"429"`).
141    pub fn machine_code(&self) -> Option<String> {
142        self.code
143            .clone()
144            .or_else(|| self.located(|envelope| envelope.code()))
145    }
146
147    /// The error the body's envelope holds, as `{"error": ...}`, or the
148    /// error event itself; `None` when the body carries no envelope.
149    pub fn envelope_json(&self) -> Option<serde_json::Value> {
150        let doc: serde_json::Value = serde_json::from_str(&self.body).ok()?;
151        let envelope = envelope(&doc)?;
152        let error = envelope.error?.clone();
153        Some(match envelope.nested {
154            true => serde_json::json!({ "error": error }),
155            false => error,
156        })
157    }
158
159    /// `f` applied to the error the body carries, as [`delivered`] finds it.
160    fn located<T>(&self, f: impl FnOnce(Envelope<'_>) -> Option<T>) -> Option<T> {
161        let doc: serde_json::Value = serde_json::from_str(&self.body).ok()?;
162        delivered(&doc).and_then(f)
163    }
164
165    /// Attach the transport request id the failed response reported.
166    pub fn with_provider_request_id(mut self, request_id: Option<String>) -> Self {
167        self.provider_request_id = request_id.filter(|id| !id.is_empty());
168        self
169    }
170
171    /// Replaces captured response headers, including rate-limit metadata.
172    pub fn with_headers(mut self, headers: Option<http::HeaderMap>) -> Self {
173        self.headers = headers;
174        self
175    }
176}
177
178impl std::fmt::Display for ProviderResponseError {
179    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
180        match self.status {
181            Some(status) => write!(f, "status {status}: {}", self.body)?,
182            None => write!(f, "{}", self.body)?,
183        }
184        // The id support asks for belongs in the message a caller logs.
185        if let Some(request_id) = &self.provider_request_id {
186            write!(f, " (request id: {request_id})")?;
187        }
188        if let Some(route) = &self.route {
189            write!(f, " [{route}]")?;
190        }
191        Ok(())
192    }
193}
194
195impl std::error::Error for ProviderResponseError {}
196
197/// Serialized error metadata with numeric HTTP status and no headers.
198/// Volatile transport headers are excluded to keep replay records stable.
199#[derive(serde::Serialize, serde::Deserialize)]
200#[serde(deny_unknown_fields)]
201struct ProviderResponseErrorWire {
202    status: Option<u16>,
203    body: String,
204    provider_request_id: Option<String>,
205    #[serde(default, skip_serializing_if = "Option::is_none")]
206    code: Option<String>,
207    #[serde(default, skip_serializing_if = "Option::is_none")]
208    transient: Option<bool>,
209    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
210    refusal: bool,
211}
212
213impl serde::Serialize for ProviderResponseError {
214    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
215        ProviderResponseErrorWire {
216            status: self.status.map(|status| status.as_u16()),
217            body: self.body.clone(),
218            provider_request_id: self.provider_request_id.clone(),
219            code: self.code.clone(),
220            transient: self.transient,
221            refusal: self.refusal,
222        }
223        .serialize(serializer)
224    }
225}
226
227impl<'de> serde::Deserialize<'de> for ProviderResponseError {
228    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
229        use serde::de::Error as _;
230        let wire = ProviderResponseErrorWire::deserialize(deserializer)?;
231        let status = wire
232            .status
233            .map(StatusCode::from_u16)
234            .transpose()
235            .map_err(D::Error::custom)?;
236        Ok(Self {
237            status,
238            body: wire.body,
239            provider_request_id: wire.provider_request_id,
240            headers: None,
241            code: wire.code,
242            transient: wire.transient,
243            refusal: wire.refusal,
244            route: None,
245        })
246    }
247}
248
249/// Where a provider put its error, and the code it gave it: the first
250/// nonempty string and the first integer among its code fields.
251#[derive(Default)]
252struct Envelope<'a> {
253    /// The error value itself: an object, a message string, or the event.
254    error: Option<&'a serde_json::Value>,
255    name: Option<&'a str>,
256    number: Option<i64>,
257    /// The error nests in the document (`error`, `response.error`) rather
258    /// than being the document itself, an `error` event.
259    nested: bool,
260}
261
262/// Codes naming a transient condition, in any case, from every transport:
263/// HTTP envelopes, gRPC status names, AWS exception types.
264const TRANSIENT: &[&str] = &[
265    "overloaded",
266    "overloaded_error",
267    "api_error",
268    "rate_limit_error",
269    "rate_limit_exceeded",
270    "too_many_requests",
271    "server_error",
272    "server_is_overloaded",
273    "slow_down",
274    "unavailable",
275    "resource_exhausted",
276    "deadline_exceeded",
277    "aborted",
278    "ThrottlingException",
279    "ServiceUnavailableException",
280    "InternalServerException",
281    "ModelNotReadyException",
282    "ModelTimeoutException",
283    "ModelStreamErrorException",
284];
285
286/// Codes naming a condition the same request meets again.
287const FINAL: &[&str] = &[
288    "insufficient_quota",
289    "quota_exceeded",
290    "billing_hard_limit_reached",
291    "context_length_exceeded",
292    "invalid_prompt",
293];
294
295/// The one reader of where a provider puts its error. In order: the
296/// Responses `response.failed` nesting (`response.error`); a top-level
297/// `error` object, or a nonempty `error` string (a message, no code); a
298/// document that is itself an `error` event, whose code is its `code`
299/// alone, since its `type` is the event tag. `null`, `{}` and `""` are no
300/// envelope. Whether a frame is an error at all stays its decoder's call.
301fn envelope(doc: &serde_json::Value) -> Option<Envelope<'_>> {
302    use serde_json::Value;
303    const FIELDS: &[&str] = &["code", "status", "type"];
304    let object = |value: &&Value| value.as_object().is_some_and(|fields| !fields.is_empty());
305    if let Some(error) = doc.pointer("/response/error").filter(object) {
306        return Some(Envelope::of(error, FIELDS, true));
307    }
308    match doc.get("error") {
309        Some(error) if object(&error) => Some(Envelope::of(error, FIELDS, true)),
310        Some(error @ Value::String(message)) if !message.is_empty() => {
311            Some(Envelope::of(error, &[], true))
312        }
313        _ => (doc.get("type").and_then(Value::as_str) == Some("error"))
314            .then(|| Envelope::of(doc, &["code"], false)),
315    }
316}
317
318/// The error a body already known to be one carries, for its verdict and
319/// code: where [`envelope`] locates it; in a JSON array (Gemini's non-SSE
320/// stream), the first element that carries one; else the document read as
321/// a bare error object, as a decoder that handed over the inner error
322/// (`{"type":"overloaded_error","message":".."}`) leaves it. A bare error
323/// has a nonempty string `message` and no `error` or `response` of its own,
324/// and its code is its `code`, `status` or `type`.
325fn delivered(doc: &serde_json::Value) -> Option<Envelope<'_>> {
326    if let Some(items) = doc.as_array() {
327        return items.iter().find_map(delivered);
328    }
329    let message = doc.get("message").and_then(serde_json::Value::as_str);
330    let bare = message.is_some_and(|message| !message.is_empty())
331        && doc.get("error").is_none()
332        && doc.get("response").is_none();
333    envelope(doc).or_else(|| bare.then(|| Envelope::of(doc, &["code", "status", "type"], false)))
334}
335
336impl<'a> Envelope<'a> {
337    fn named(mut self, name: &'a str) -> Self {
338        self.name = Some(name);
339        self
340    }
341
342    fn of(error: &'a serde_json::Value, fields: &[&str], nested: bool) -> Self {
343        let values = || fields.iter().filter_map(|field| error.get(field));
344        Self {
345            error: Some(error),
346            name: values().find_map(|value| value.as_str().filter(|name| !name.is_empty())),
347            number: values().find_map(serde_json::Value::as_i64),
348            nested,
349        }
350    }
351
352    /// The name when there is one, as it says more than a number.
353    fn code(&self) -> Option<String> {
354        let number = || self.number.map(|number| number.to_string());
355        self.name.map(str::to_owned).or_else(number)
356    }
357
358    /// The one provider code → retry verdict table, beside
359    /// [`crate::error::retryable_status`]: what the name says, else what
360    /// the number says read as an HTTP status, else nothing. gRPC
361    /// `INTERNAL` stays out, as its transports have always left it.
362    fn verdict(&self) -> Option<bool> {
363        let status = || {
364            self.http_status()
365                .map(|s| crate::error::retryable_status(Some(s)))
366        };
367        (self.named_in(TRANSIENT).then_some(true))
368            .or_else(|| self.is_final().then_some(false))
369            .or_else(status)
370    }
371
372    /// Whether the name is one of [`FINAL`].
373    fn is_final(&self) -> bool {
374        self.named_in(FINAL)
375    }
376
377    fn named_in(&self, codes: &[&str]) -> bool {
378        let name = self.name.unwrap_or_default();
379        codes.iter().any(|code| code.eq_ignore_ascii_case(name))
380    }
381
382    fn http_status(&self) -> Option<u16> {
383        let number = u16::try_from(self.number?).ok();
384        number.filter(|number| (400..=599).contains(number))
385    }
386}
387
388/// An id or model name as a response carries it: an empty one is none.
389pub(crate) fn reported(id: Option<String>) -> Option<String> {
390    id.filter(|id| !id.is_empty())
391}
392
393/// Parses an optional response body as JSON.
394///
395/// Returns:
396/// - `Ok(Some(value))` when a body is present and valid JSON.
397/// - `Ok(None)` when the body is absent or empty.
398/// - `Err(error)` when a body is present but isn't valid JSON.
399pub(crate) fn json(body: Option<&str>) -> Result<Option<serde_json::Value>, serde_json::Error> {
400    body.filter(|body| !body.is_empty())
401        .map(serde_json::from_str)
402        .transpose()
403}
404
405#[cfg(test)]
406mod tests;