Skip to main content

ramvamp_server/
error.rs

1//! Typed request/response errors and their HTTP mapping.
2//!
3//! Every failure this crate can report is one [`ServerError`] variant, and a
4//! variant knows its own status, body and headers. The transport lane never
5//! decides a status code: it asks the error.
6//!
7//! The body shape is OpenAI's, because that is what the clients parse:
8//!
9//! ```json
10//! {"error":{"message":"...","type":"...","param":null,"code":"..."}}
11//! ```
12//!
13//! `message` is a plain `String`, never `null` and never absent — at least one
14//! widely used client models the field as required and fails to deserialize
15//! the error before it can report it, which turns a clear 400 into a parse
16//! crash. `param` and `code` are always *present* keys, `null` when they do
17//! not apply, for the same reason.
18
19use serde::{Deserialize, Serialize};
20use thiserror::Error;
21
22use ramvamp_core::generate::GenerateError;
23use ramvamp_core::model::ForwardError;
24use ramvamp_core::tokenizer::TokenizerError;
25
26/// OpenAI's `invalid_request_error`: the client sent something this server
27/// cannot honour, and retrying the same bytes will fail the same way.
28pub const TYPE_INVALID_REQUEST: &str = "invalid_request_error";
29
30/// OpenAI's `server_error`: the request was fine, this process is not (yet)
31/// able to serve it.
32pub const TYPE_SERVER: &str = "server_error";
33
34/// Headers a client should see on a 503, exposed as data because building
35/// them is the transport lane's job and choosing them is this one's.
36///
37/// `Retry-After` is deliberately **1**, not the true wait.
38///
39/// The true wait for a busy single-session server is the remainder of the
40/// in-flight reply, which at ~2 tok/s decode is routinely minutes. Sending
41/// that honest number disables retrying altogether: openai-python's
42/// `_should_retry` inspects `Retry-After` first and treats any value above
43/// 120 seconds as "do not retry", returning the error to the caller instead
44/// of waiting. A small number keeps the client in its own backoff loop, which
45/// is the behaviour we actually want. Do not "fix" this to a truthful value.
46pub const RETRY_HEADERS: &[(&str, &str)] = &[
47    ("Retry-After", "1"),
48    ("retry-after-ms", "500"),
49    ("x-should-retry", "true"),
50];
51
52/// The `error` object inside an error body.
53#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
54pub struct ErrorDetail {
55    /// Human-readable explanation. Always a string.
56    pub message: String,
57    /// Error class, one of [`TYPE_INVALID_REQUEST`] / [`TYPE_SERVER`].
58    #[serde(rename = "type")]
59    pub kind: String,
60    /// The offending request field, when one can be named.
61    pub param: Option<String>,
62    /// Stable machine-readable code.
63    pub code: Option<String>,
64}
65
66/// The whole error body: `{"error": {...}}`.
67#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
68pub struct ErrorResponse {
69    /// The error itself.
70    pub error: ErrorDetail,
71}
72
73/// Everything this crate can refuse to do.
74///
75/// Carries enough data to build the body without re-deriving it: an overflow
76/// knows both numbers, a rejected content part knows its `type`.
77#[derive(Debug, Error)]
78pub enum ServerError {
79    /// The body is not JSON, or not JSON of the expected shape. Carries
80    /// serde's message, which names the line, column and field.
81    #[error("invalid request body: {0}")]
82    MalformedJson(String),
83
84    /// `messages` was absent-but-defaulted or `[]`. There is no prompt to
85    /// build, and rendering an empty conversation would make the model answer
86    /// from nothing at all.
87    #[error("`messages` must contain at least one message")]
88    EmptyMessages,
89
90    /// `n > 1`. A single-session server has one decode loop; returning one
91    /// choice and calling it `n` would be a silent wrong answer, so it is
92    /// refused loudly instead.
93    #[error("`n` must be 1: this server generates a single completion per request (got {n})")]
94    MultipleChoices {
95        /// What the client asked for.
96        n: u32,
97    },
98
99    /// A content part this build cannot render, e.g. `image_url`.
100    ///
101    /// Rejected rather than dropped: the pinned ChatML template coerces
102    /// non-string content to `""`, so silently discarding the part makes the
103    /// model answer a question it was never asked.
104    #[error("unsupported content part `{kind}`: only `text` parts are supported")]
105    UnsupportedContentPart {
106        /// The part's `type` field, verbatim.
107        kind: String,
108    },
109
110    /// A `text` content part with no `text` field.
111    #[error("content part of type `text` is missing its `text` field")]
112    MissingPartText,
113
114    /// A tool name outside the charset OpenAI itself constrains names to.
115    ///
116    /// Validated and refused rather than sanitized, unlike message content.
117    /// A name is not prose: the model echoes it back verbatim and the client
118    /// matches the reply against the name it sent, so breaking a hostile name
119    /// with a zero-width marker would produce a call nobody can match and a
120    /// difference nobody can see in a log. Refusing the request is the only
121    /// outcome the client can act on.
122    #[error(
123        "invalid tool name `{name}`: names must match {}",
124        crate::request::TOOL_NAME_PATTERN
125    )]
126    InvalidToolName {
127        /// The offending name, verbatim, so a client can find it.
128        name: String,
129        /// Which request field carried it: `tools` for a definition,
130        /// `messages` for a call echoed back on an assistant turn.
131        param: &'static str,
132    },
133
134    /// A `tool_choice` this build cannot honour: `required`, a named
135    /// function, or any value that is not `auto` or `none`.
136    ///
137    /// The vendored template has no way to express "you must call a
138    /// function": it branches on `tools` alone. Rendering the definitions and
139    /// letting the model choose freely would answer 200 to a request whose
140    /// central constraint was dropped.
141    #[error(
142        "`tool_choice` {choice} is not supported: this build cannot force a particular \
143         call; send `auto`, `none`, or omit it"
144    )]
145    UnsupportedToolChoice {
146        /// What the client asked for, as JSON.
147        choice: String,
148    },
149
150    /// A non-empty `stop`.
151    ///
152    /// Accepted-and-ignored until now: nothing in the runtime consumes a stop
153    /// string, so generation ran past where the caller asked it to end and the
154    /// client had no way to tell. Refused until stop strings exist.
155    #[error(
156        "`stop` is not supported by this build: generation ends on the model's own \
157         stop tokens, so a stop sequence would be accepted and never applied"
158    )]
159    StopUnsupported,
160
161    /// The prompt plus the reservation for the reply exceeds the context.
162    ///
163    /// The message names the limit because a client that cannot see it has no
164    /// way to trim the conversation to fit.
165    #[error(
166        "context: this request needs {requested} of {limit} tokens; \
167         send a shorter conversation or a smaller `max_completion_tokens`"
168    )]
169    ContextOverflow {
170        /// Prompt tokens plus the tokens reserved for the reply.
171        requested: usize,
172        /// The context cap this server was started with.
173        limit: usize,
174    },
175
176    /// The weights are still being opened. Transient; the same request will
177    /// succeed once loading finishes.
178    #[error("model is still loading")]
179    ModelLoading,
180
181    /// A generation is already in flight. Transient in exactly the same way,
182    /// and reported the same way.
183    ///
184    /// 503, not 429. Retry behaviour is identical across the clients we care
185    /// about, but 429 makes openai-python raise `RateLimitError`, which
186    /// surfaces to a user as a quota or billing message — nonsense from a
187    /// server running on their own machine.
188    #[error("server is busy: this build serves one request at a time")]
189    AtCapacity,
190
191    /// No route serves this method and path.
192    ///
193    /// A 404 with the same body shape as every other refusal, because a
194    /// client pointed at the wrong base URL parses the error before it can
195    /// report it, and an empty body or an HTML page turns "wrong path" into
196    /// "the server is broken".
197    #[error("invalid URL ({method} {path})")]
198    NotFound {
199        /// The request method, verbatim.
200        method: String,
201        /// The request path, query string stripped.
202        path: String,
203    },
204
205    /// The request body is larger than this server will buffer.
206    ///
207    /// The body is read into memory to be parsed, and this process is meant
208    /// to run inside a 3 GB cgroup alongside a model: an unbounded read is an
209    /// OOM with a `Content-Length` header for a trigger. The cap is generous
210    /// against a 4K context and small against the budget.
211    #[error("request body is larger than the {limit}-byte limit")]
212    BodyTooLarge {
213        /// The cap, in bytes.
214        limit: usize,
215    },
216
217    /// Rendering or encoding the prompt failed.
218    #[error(transparent)]
219    Tokenizer(#[from] TokenizerError),
220
221    /// Generation failed inside the runtime.
222    ///
223    /// Reported as a 500 rather than mapped onto a 400: every input-shaped
224    /// failure is caught before generation starts (see
225    /// [`ServerError::ContextOverflow`] and
226    /// [`ChatCompletionRequest::validate`](crate::request::ChatCompletionRequest::validate)),
227    /// so anything that reaches here is this process's problem.
228    #[error(transparent)]
229    Generate(#[from] GenerateError),
230
231    /// The KV cache could not be rewound to the prefix a request shares with
232    /// the one before it. Same reasoning as [`ServerError::Generate`].
233    #[error(transparent)]
234    Forward(#[from] ForwardError),
235
236    /// A response could not be serialized. Unreachable for the types in this
237    /// crate (no maps with non-string keys, no failing `Serialize` impls);
238    /// reported rather than unwrapped so that stays true by construction.
239    #[error("failed to serialize response: {0}")]
240    Serialize(#[from] serde_json::Error),
241}
242
243impl ServerError {
244    /// The HTTP status for this error.
245    pub fn status(&self) -> u16 {
246        match self {
247            ServerError::MalformedJson(_)
248            | ServerError::EmptyMessages
249            | ServerError::MultipleChoices { .. }
250            | ServerError::UnsupportedContentPart { .. }
251            | ServerError::MissingPartText
252            | ServerError::InvalidToolName { .. }
253            | ServerError::UnsupportedToolChoice { .. }
254            | ServerError::StopUnsupported
255            | ServerError::ContextOverflow { .. } => 400,
256            ServerError::NotFound { .. } => 404,
257            ServerError::BodyTooLarge { .. } => 413,
258            ServerError::ModelLoading | ServerError::AtCapacity => 503,
259            ServerError::Tokenizer(_)
260            | ServerError::Generate(_)
261            | ServerError::Forward(_)
262            | ServerError::Serialize(_) => 500,
263        }
264    }
265
266    /// The `error.type` string.
267    ///
268    /// 404 and 413 join the 400s: all three say the client sent something
269    /// this server will not serve, which is what `invalid_request_error`
270    /// means to the SDKs that switch on it.
271    pub fn kind(&self) -> &'static str {
272        match self.status() {
273            400 | 404 | 413 => TYPE_INVALID_REQUEST,
274            _ => TYPE_SERVER,
275        }
276    }
277
278    /// The request field at fault, when one can be named.
279    pub fn param(&self) -> Option<&'static str> {
280        match self {
281            ServerError::EmptyMessages
282            | ServerError::UnsupportedContentPart { .. }
283            | ServerError::MissingPartText
284            | ServerError::ContextOverflow { .. } => Some("messages"),
285            // The one error that can come from either of two fields, so it
286            // carries the answer rather than guessing one.
287            ServerError::InvalidToolName { param, .. } => Some(*param),
288            ServerError::UnsupportedToolChoice { .. } => Some("tool_choice"),
289            ServerError::StopUnsupported => Some("stop"),
290            ServerError::MultipleChoices { .. } => Some("n"),
291            ServerError::MalformedJson(_)
292            | ServerError::NotFound { .. }
293            | ServerError::BodyTooLarge { .. }
294            | ServerError::ModelLoading
295            | ServerError::AtCapacity
296            | ServerError::Tokenizer(_)
297            | ServerError::Generate(_)
298            | ServerError::Forward(_)
299            | ServerError::Serialize(_) => None,
300        }
301    }
302
303    /// The stable machine-readable code.
304    pub fn code(&self) -> &'static str {
305        match self {
306            ServerError::MalformedJson(_) => "invalid_json",
307            ServerError::EmptyMessages => "empty_messages",
308            ServerError::MultipleChoices { .. } => "unsupported_value",
309            ServerError::UnsupportedContentPart { .. } => "unsupported_content_part",
310            ServerError::MissingPartText => "invalid_content_part",
311            ServerError::InvalidToolName { .. } => "invalid_tool_name",
312            ServerError::UnsupportedToolChoice { .. } => "unsupported_value",
313            ServerError::StopUnsupported => "unsupported_value",
314            // OpenAI's own code for this case; clients special-case the
315            // string, so it is worth matching exactly.
316            ServerError::ContextOverflow { .. } => "context_length_exceeded",
317            ServerError::NotFound { .. } => "not_found",
318            ServerError::BodyTooLarge { .. } => "request_too_large",
319            ServerError::ModelLoading => "model_loading",
320            ServerError::AtCapacity => "server_busy",
321            ServerError::Tokenizer(_) => "tokenizer_error",
322            ServerError::Generate(_) => "generate_error",
323            ServerError::Forward(_) => "forward_error",
324            ServerError::Serialize(_) => "internal_error",
325        }
326    }
327
328    /// Headers to send alongside the body.
329    ///
330    /// Both 503s get [`RETRY_HEADERS`]: loading and busy are the same promise
331    /// to the client — come back shortly and this will work.
332    pub fn headers(&self) -> &'static [(&'static str, &'static str)] {
333        match self {
334            ServerError::ModelLoading | ServerError::AtCapacity => RETRY_HEADERS,
335            _ => &[],
336        }
337    }
338
339    /// The full error body.
340    pub fn body(&self) -> ErrorResponse {
341        ErrorResponse {
342            error: ErrorDetail {
343                message: self.to_string(),
344                kind: self.kind().to_owned(),
345                param: self.param().map(str::to_owned),
346                code: Some(self.code().to_owned()),
347            },
348        }
349    }
350
351    /// The full error body, serialized. Falls back to a hand-built body if
352    /// serialization somehow fails, so an error path can never panic and can
353    /// never return something without a `message`.
354    pub fn body_json(&self) -> String {
355        serde_json::to_string(&self.body()).unwrap_or_else(|_| {
356            r#"{"error":{"message":"internal error","type":"server_error","param":null,"code":"internal_error"}}"#
357                .to_owned()
358        })
359    }
360}
361
362#[cfg(test)]
363mod tests {
364    use super::*;
365
366    /// The full status/type/param/code table, pinned. A change here is a
367    /// change to the wire contract, not a refactor.
368    #[test]
369    fn every_error_maps_to_its_status_and_code() {
370        let cases: Vec<(ServerError, u16, &str, Option<&str>, &str)> = vec![
371            (
372                ServerError::MalformedJson("expected value at line 1".into()),
373                400,
374                TYPE_INVALID_REQUEST,
375                None,
376                "invalid_json",
377            ),
378            (
379                ServerError::EmptyMessages,
380                400,
381                TYPE_INVALID_REQUEST,
382                Some("messages"),
383                "empty_messages",
384            ),
385            (
386                ServerError::MultipleChoices { n: 2 },
387                400,
388                TYPE_INVALID_REQUEST,
389                Some("n"),
390                "unsupported_value",
391            ),
392            (
393                ServerError::UnsupportedContentPart {
394                    kind: "image_url".into(),
395                },
396                400,
397                TYPE_INVALID_REQUEST,
398                Some("messages"),
399                "unsupported_content_part",
400            ),
401            (
402                ServerError::MissingPartText,
403                400,
404                TYPE_INVALID_REQUEST,
405                Some("messages"),
406                "invalid_content_part",
407            ),
408            (
409                ServerError::InvalidToolName {
410                    name: "get weather".into(),
411                    param: "tools",
412                },
413                400,
414                TYPE_INVALID_REQUEST,
415                Some("tools"),
416                "invalid_tool_name",
417            ),
418            (
419                ServerError::InvalidToolName {
420                    name: "get weather".into(),
421                    param: "messages",
422                },
423                400,
424                TYPE_INVALID_REQUEST,
425                Some("messages"),
426                "invalid_tool_name",
427            ),
428            (
429                ServerError::UnsupportedToolChoice {
430                    choice: r#"{"type":"function"}"#.into(),
431                },
432                400,
433                TYPE_INVALID_REQUEST,
434                Some("tool_choice"),
435                "unsupported_value",
436            ),
437            (
438                ServerError::StopUnsupported,
439                400,
440                TYPE_INVALID_REQUEST,
441                Some("stop"),
442                "unsupported_value",
443            ),
444            (
445                ServerError::ContextOverflow {
446                    requested: 5000,
447                    limit: 4096,
448                },
449                400,
450                TYPE_INVALID_REQUEST,
451                Some("messages"),
452                "context_length_exceeded",
453            ),
454            (
455                ServerError::NotFound {
456                    method: "GET".into(),
457                    path: "/v1/embeddings".into(),
458                },
459                404,
460                TYPE_INVALID_REQUEST,
461                None,
462                "not_found",
463            ),
464            (
465                ServerError::BodyTooLarge { limit: 1_048_576 },
466                413,
467                TYPE_INVALID_REQUEST,
468                None,
469                "request_too_large",
470            ),
471            (
472                ServerError::ModelLoading,
473                503,
474                TYPE_SERVER,
475                None,
476                "model_loading",
477            ),
478            (
479                ServerError::AtCapacity,
480                503,
481                TYPE_SERVER,
482                None,
483                "server_busy",
484            ),
485            (
486                ServerError::Tokenizer(TokenizerError::Encode("boom".into())),
487                500,
488                TYPE_SERVER,
489                None,
490                "tokenizer_error",
491            ),
492        ];
493
494        for (error, status, kind, param, code) in cases {
495            assert_eq!(error.status(), status, "{error:?}");
496            assert_eq!(error.kind(), kind, "{error:?}");
497            assert_eq!(error.param(), param, "{error:?}");
498            assert_eq!(error.code(), code, "{error:?}");
499
500            let body = error.body();
501            assert_eq!(body.error.kind, kind);
502            assert_eq!(body.error.param.as_deref(), param);
503            assert_eq!(body.error.code.as_deref(), Some(code));
504        }
505    }
506
507    #[test]
508    fn error_message_is_always_a_non_empty_string() {
509        for error in [
510            ServerError::MalformedJson(String::new()),
511            ServerError::EmptyMessages,
512            ServerError::MultipleChoices { n: 4 },
513            ServerError::UnsupportedContentPart {
514                kind: String::new(),
515            },
516            ServerError::MissingPartText,
517            ServerError::InvalidToolName {
518                name: String::new(),
519                param: "tools",
520            },
521            ServerError::UnsupportedToolChoice {
522                choice: String::new(),
523            },
524            ServerError::StopUnsupported,
525            ServerError::ContextOverflow {
526                requested: 1,
527                limit: 0,
528            },
529            ServerError::NotFound {
530                method: String::new(),
531                path: String::new(),
532            },
533            ServerError::BodyTooLarge { limit: 0 },
534            ServerError::ModelLoading,
535            ServerError::AtCapacity,
536        ] {
537            let body = error.body();
538            assert!(!body.error.message.is_empty(), "{error:?}");
539            // Present as a JSON string, never null: a known client's schema
540            // makes the field required.
541            let json = error.body_json();
542            assert!(
543                json.contains(r#""message":""#) || json.contains(r#""message":"#),
544                "{json}"
545            );
546            assert!(!json.contains(r#""message":null"#), "{json}");
547        }
548    }
549
550    #[test]
551    fn context_overflow_names_the_limit() {
552        let error = ServerError::ContextOverflow {
553            requested: 5000,
554            limit: 4096,
555        };
556        let message = error.body().error.message;
557        assert!(message.contains("4096"), "{message}");
558        assert!(message.contains("5000"), "{message}");
559    }
560
561    /// The offending name has to reach the client: a caller whose tool list is
562    /// generated cannot find the bad entry from "invalid tool name" alone.
563    #[test]
564    fn an_invalid_tool_name_error_quotes_the_name_and_the_rule() {
565        let error = ServerError::InvalidToolName {
566            name: "read<file>".into(),
567            param: "tools",
568        };
569        let message = error.body().error.message;
570        assert!(message.contains("read<file>"), "{message}");
571        assert!(
572            message.contains(crate::request::TOOL_NAME_PATTERN),
573            "{message}"
574        );
575    }
576
577    #[test]
578    fn only_the_503s_carry_retry_headers() {
579        assert_eq!(ServerError::AtCapacity.headers(), RETRY_HEADERS);
580        assert_eq!(ServerError::ModelLoading.headers(), RETRY_HEADERS);
581        assert!(ServerError::EmptyMessages.headers().is_empty());
582    }
583
584    /// openai-python's `_should_retry` reads `Retry-After` first and gives up
585    /// when it exceeds 120 seconds. An honest wait for this server is minutes,
586    /// so an honest header would silently switch retrying off.
587    #[test]
588    fn retry_after_stays_under_the_client_give_up_threshold() {
589        let retry_after = RETRY_HEADERS
590            .iter()
591            .find(|(name, _)| *name == "Retry-After")
592            .map(|(_, value)| *value);
593        assert_eq!(retry_after, Some("1"));
594        let seconds: u64 = retry_after.and_then(|v| v.parse().ok()).unwrap_or(u64::MAX);
595        assert!(seconds <= 120, "an honest Retry-After disables retrying");
596    }
597
598    /// 429 would make openai-python raise `RateLimitError`, which reads as a
599    /// quota problem to a user running the server on their own machine.
600    #[test]
601    fn capacity_is_503_not_429() {
602        assert_eq!(ServerError::AtCapacity.status(), 503);
603    }
604
605    #[test]
606    fn error_body_has_the_openai_shape() {
607        let json = ServerError::EmptyMessages.body_json();
608        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
609        let error = &parsed["error"];
610        assert!(error["message"].is_string());
611        assert_eq!(error["type"], TYPE_INVALID_REQUEST);
612        assert_eq!(error["param"], "messages");
613        assert_eq!(error["code"], "empty_messages");
614        // `param` and `code` are always present keys, null when they do not
615        // apply, rather than omitted.
616        let json = ServerError::ModelLoading.body_json();
617        assert!(json.contains(r#""param":null"#), "{json}");
618    }
619}