use serde::{Deserialize, Serialize};
use thiserror::Error;
use ramvamp_core::generate::GenerateError;
use ramvamp_core::model::ForwardError;
use ramvamp_core::tokenizer::TokenizerError;
pub const TYPE_INVALID_REQUEST: &str = "invalid_request_error";
pub const TYPE_SERVER: &str = "server_error";
pub const RETRY_HEADERS: &[(&str, &str)] = &[
("Retry-After", "1"),
("retry-after-ms", "500"),
("x-should-retry", "true"),
];
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorDetail {
pub message: String,
#[serde(rename = "type")]
pub kind: String,
pub param: Option<String>,
pub code: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorResponse {
pub error: ErrorDetail,
}
#[derive(Debug, Error)]
pub enum ServerError {
#[error("invalid request body: {0}")]
MalformedJson(String),
#[error("`messages` must contain at least one message")]
EmptyMessages,
#[error("`n` must be 1: this server generates a single completion per request (got {n})")]
MultipleChoices {
n: u32,
},
#[error("unsupported content part `{kind}`: only `text` parts are supported")]
UnsupportedContentPart {
kind: String,
},
#[error("content part of type `text` is missing its `text` field")]
MissingPartText,
#[error(
"invalid tool name `{name}`: names must match {}",
crate::request::TOOL_NAME_PATTERN
)]
InvalidToolName {
name: String,
param: &'static str,
},
#[error(
"`tool_choice` {choice} is not supported: this build cannot force a particular \
call; send `auto`, `none`, or omit it"
)]
UnsupportedToolChoice {
choice: String,
},
#[error(
"`stop` is not supported by this build: generation ends on the model's own \
stop tokens, so a stop sequence would be accepted and never applied"
)]
StopUnsupported,
#[error(
"context: this request needs {requested} of {limit} tokens; \
send a shorter conversation or a smaller `max_completion_tokens`"
)]
ContextOverflow {
requested: usize,
limit: usize,
},
#[error("model is still loading")]
ModelLoading,
#[error("server is busy: this build serves one request at a time")]
AtCapacity,
#[error("invalid URL ({method} {path})")]
NotFound {
method: String,
path: String,
},
#[error("request body is larger than the {limit}-byte limit")]
BodyTooLarge {
limit: usize,
},
#[error(transparent)]
Tokenizer(#[from] TokenizerError),
#[error(transparent)]
Generate(#[from] GenerateError),
#[error(transparent)]
Forward(#[from] ForwardError),
#[error("failed to serialize response: {0}")]
Serialize(#[from] serde_json::Error),
}
impl ServerError {
pub fn status(&self) -> u16 {
match self {
ServerError::MalformedJson(_)
| ServerError::EmptyMessages
| ServerError::MultipleChoices { .. }
| ServerError::UnsupportedContentPart { .. }
| ServerError::MissingPartText
| ServerError::InvalidToolName { .. }
| ServerError::UnsupportedToolChoice { .. }
| ServerError::StopUnsupported
| ServerError::ContextOverflow { .. } => 400,
ServerError::NotFound { .. } => 404,
ServerError::BodyTooLarge { .. } => 413,
ServerError::ModelLoading | ServerError::AtCapacity => 503,
ServerError::Tokenizer(_)
| ServerError::Generate(_)
| ServerError::Forward(_)
| ServerError::Serialize(_) => 500,
}
}
pub fn kind(&self) -> &'static str {
match self.status() {
400 | 404 | 413 => TYPE_INVALID_REQUEST,
_ => TYPE_SERVER,
}
}
pub fn param(&self) -> Option<&'static str> {
match self {
ServerError::EmptyMessages
| ServerError::UnsupportedContentPart { .. }
| ServerError::MissingPartText
| ServerError::ContextOverflow { .. } => Some("messages"),
ServerError::InvalidToolName { param, .. } => Some(*param),
ServerError::UnsupportedToolChoice { .. } => Some("tool_choice"),
ServerError::StopUnsupported => Some("stop"),
ServerError::MultipleChoices { .. } => Some("n"),
ServerError::MalformedJson(_)
| ServerError::NotFound { .. }
| ServerError::BodyTooLarge { .. }
| ServerError::ModelLoading
| ServerError::AtCapacity
| ServerError::Tokenizer(_)
| ServerError::Generate(_)
| ServerError::Forward(_)
| ServerError::Serialize(_) => None,
}
}
pub fn code(&self) -> &'static str {
match self {
ServerError::MalformedJson(_) => "invalid_json",
ServerError::EmptyMessages => "empty_messages",
ServerError::MultipleChoices { .. } => "unsupported_value",
ServerError::UnsupportedContentPart { .. } => "unsupported_content_part",
ServerError::MissingPartText => "invalid_content_part",
ServerError::InvalidToolName { .. } => "invalid_tool_name",
ServerError::UnsupportedToolChoice { .. } => "unsupported_value",
ServerError::StopUnsupported => "unsupported_value",
ServerError::ContextOverflow { .. } => "context_length_exceeded",
ServerError::NotFound { .. } => "not_found",
ServerError::BodyTooLarge { .. } => "request_too_large",
ServerError::ModelLoading => "model_loading",
ServerError::AtCapacity => "server_busy",
ServerError::Tokenizer(_) => "tokenizer_error",
ServerError::Generate(_) => "generate_error",
ServerError::Forward(_) => "forward_error",
ServerError::Serialize(_) => "internal_error",
}
}
pub fn headers(&self) -> &'static [(&'static str, &'static str)] {
match self {
ServerError::ModelLoading | ServerError::AtCapacity => RETRY_HEADERS,
_ => &[],
}
}
pub fn body(&self) -> ErrorResponse {
ErrorResponse {
error: ErrorDetail {
message: self.to_string(),
kind: self.kind().to_owned(),
param: self.param().map(str::to_owned),
code: Some(self.code().to_owned()),
},
}
}
pub fn body_json(&self) -> String {
serde_json::to_string(&self.body()).unwrap_or_else(|_| {
r#"{"error":{"message":"internal error","type":"server_error","param":null,"code":"internal_error"}}"#
.to_owned()
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_error_maps_to_its_status_and_code() {
let cases: Vec<(ServerError, u16, &str, Option<&str>, &str)> = vec![
(
ServerError::MalformedJson("expected value at line 1".into()),
400,
TYPE_INVALID_REQUEST,
None,
"invalid_json",
),
(
ServerError::EmptyMessages,
400,
TYPE_INVALID_REQUEST,
Some("messages"),
"empty_messages",
),
(
ServerError::MultipleChoices { n: 2 },
400,
TYPE_INVALID_REQUEST,
Some("n"),
"unsupported_value",
),
(
ServerError::UnsupportedContentPart {
kind: "image_url".into(),
},
400,
TYPE_INVALID_REQUEST,
Some("messages"),
"unsupported_content_part",
),
(
ServerError::MissingPartText,
400,
TYPE_INVALID_REQUEST,
Some("messages"),
"invalid_content_part",
),
(
ServerError::InvalidToolName {
name: "get weather".into(),
param: "tools",
},
400,
TYPE_INVALID_REQUEST,
Some("tools"),
"invalid_tool_name",
),
(
ServerError::InvalidToolName {
name: "get weather".into(),
param: "messages",
},
400,
TYPE_INVALID_REQUEST,
Some("messages"),
"invalid_tool_name",
),
(
ServerError::UnsupportedToolChoice {
choice: r#"{"type":"function"}"#.into(),
},
400,
TYPE_INVALID_REQUEST,
Some("tool_choice"),
"unsupported_value",
),
(
ServerError::StopUnsupported,
400,
TYPE_INVALID_REQUEST,
Some("stop"),
"unsupported_value",
),
(
ServerError::ContextOverflow {
requested: 5000,
limit: 4096,
},
400,
TYPE_INVALID_REQUEST,
Some("messages"),
"context_length_exceeded",
),
(
ServerError::NotFound {
method: "GET".into(),
path: "/v1/embeddings".into(),
},
404,
TYPE_INVALID_REQUEST,
None,
"not_found",
),
(
ServerError::BodyTooLarge { limit: 1_048_576 },
413,
TYPE_INVALID_REQUEST,
None,
"request_too_large",
),
(
ServerError::ModelLoading,
503,
TYPE_SERVER,
None,
"model_loading",
),
(
ServerError::AtCapacity,
503,
TYPE_SERVER,
None,
"server_busy",
),
(
ServerError::Tokenizer(TokenizerError::Encode("boom".into())),
500,
TYPE_SERVER,
None,
"tokenizer_error",
),
];
for (error, status, kind, param, code) in cases {
assert_eq!(error.status(), status, "{error:?}");
assert_eq!(error.kind(), kind, "{error:?}");
assert_eq!(error.param(), param, "{error:?}");
assert_eq!(error.code(), code, "{error:?}");
let body = error.body();
assert_eq!(body.error.kind, kind);
assert_eq!(body.error.param.as_deref(), param);
assert_eq!(body.error.code.as_deref(), Some(code));
}
}
#[test]
fn error_message_is_always_a_non_empty_string() {
for error in [
ServerError::MalformedJson(String::new()),
ServerError::EmptyMessages,
ServerError::MultipleChoices { n: 4 },
ServerError::UnsupportedContentPart {
kind: String::new(),
},
ServerError::MissingPartText,
ServerError::InvalidToolName {
name: String::new(),
param: "tools",
},
ServerError::UnsupportedToolChoice {
choice: String::new(),
},
ServerError::StopUnsupported,
ServerError::ContextOverflow {
requested: 1,
limit: 0,
},
ServerError::NotFound {
method: String::new(),
path: String::new(),
},
ServerError::BodyTooLarge { limit: 0 },
ServerError::ModelLoading,
ServerError::AtCapacity,
] {
let body = error.body();
assert!(!body.error.message.is_empty(), "{error:?}");
let json = error.body_json();
assert!(
json.contains(r#""message":""#) || json.contains(r#""message":"#),
"{json}"
);
assert!(!json.contains(r#""message":null"#), "{json}");
}
}
#[test]
fn context_overflow_names_the_limit() {
let error = ServerError::ContextOverflow {
requested: 5000,
limit: 4096,
};
let message = error.body().error.message;
assert!(message.contains("4096"), "{message}");
assert!(message.contains("5000"), "{message}");
}
#[test]
fn an_invalid_tool_name_error_quotes_the_name_and_the_rule() {
let error = ServerError::InvalidToolName {
name: "read<file>".into(),
param: "tools",
};
let message = error.body().error.message;
assert!(message.contains("read<file>"), "{message}");
assert!(
message.contains(crate::request::TOOL_NAME_PATTERN),
"{message}"
);
}
#[test]
fn only_the_503s_carry_retry_headers() {
assert_eq!(ServerError::AtCapacity.headers(), RETRY_HEADERS);
assert_eq!(ServerError::ModelLoading.headers(), RETRY_HEADERS);
assert!(ServerError::EmptyMessages.headers().is_empty());
}
#[test]
fn retry_after_stays_under_the_client_give_up_threshold() {
let retry_after = RETRY_HEADERS
.iter()
.find(|(name, _)| *name == "Retry-After")
.map(|(_, value)| *value);
assert_eq!(retry_after, Some("1"));
let seconds: u64 = retry_after.and_then(|v| v.parse().ok()).unwrap_or(u64::MAX);
assert!(seconds <= 120, "an honest Retry-After disables retrying");
}
#[test]
fn capacity_is_503_not_429() {
assert_eq!(ServerError::AtCapacity.status(), 503);
}
#[test]
fn error_body_has_the_openai_shape() {
let json = ServerError::EmptyMessages.body_json();
let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
let error = &parsed["error"];
assert!(error["message"].is_string());
assert_eq!(error["type"], TYPE_INVALID_REQUEST);
assert_eq!(error["param"], "messages");
assert_eq!(error["code"], "empty_messages");
let json = ServerError::ModelLoading.body_json();
assert!(json.contains(r#""param":null"#), "{json}");
}
}