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}