AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
//! API error handling — converts internal [`XerjError`] values into HTTP
//! responses with the correct status code and an Elasticsearch-compatible
//! JSON body.
//!
//! # ES error format
//!
//! ```json
//! {
//! "error": {
//! "root_cause": [{ "type": "index_not_found_exception", "reason": "…" }],
//! "type": "index_not_found_exception",
//! "reason": "no such index [my-index]"
//! },
//! "status": 404
//! }
//! ```
use axum::{
http::StatusCode,
response::{IntoResponse, Response},
Json,
};
use serde::Serialize;
use serde_json::{json, Value};
use xerj_common::XerjError;
// ─────────────────────────────────────────────────────────────────────────────
// ES error body
// ─────────────────────────────────────────────────────────────────────────────
/// A single cause entry inside the ES `root_cause` array.
///
/// Field order matches ES byte-for-byte for `index_not_found_exception`:
/// `type, reason, resource.type, resource.id, index_uuid, index`.
#[derive(Debug, Serialize)]
pub struct EsRootCause {
#[serde(rename = "type")]
pub error_type: String,
pub reason: String,
#[serde(rename = "resource.type", skip_serializing_if = "Option::is_none")]
pub resource_type: Option<String>,
#[serde(rename = "resource.id", skip_serializing_if = "Option::is_none")]
pub resource_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub index_uuid: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub index: Option<String>,
}
/// The inner `error` object in an ES error response.
#[derive(Debug, Serialize)]
pub struct EsErrorBody {
pub root_cause: Vec<EsRootCause>,
#[serde(rename = "type")]
pub error_type: String,
pub reason: String,
#[serde(rename = "resource.type", skip_serializing_if = "Option::is_none")]
pub resource_type: Option<String>,
#[serde(rename = "resource.id", skip_serializing_if = "Option::is_none")]
pub resource_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub index_uuid: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub index: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub request_id: Option<String>,
}
/// Top-level ES-compatible error response shape.
#[derive(Debug, Serialize)]
pub struct EsErrorResponse {
pub error: EsErrorBody,
pub status: u16,
/// Additive, non-ES field carrying an actionable recovery hint (e.g. for
/// `index_not_found_exception`: nearby index names, the `ax-*` wildcard
/// an autoindex-managed cluster searches with). Same `_xerj` convention
/// as the hint on a successful `_search` response — see
/// `es_compat::search_response_hint`. Absent whenever no handler had
/// anything more specific to offer than the `reason` string already
/// says, so this never becomes noise on errors that are already
/// self-explanatory.
#[serde(rename = "_xerj", skip_serializing_if = "Option::is_none")]
pub xerj_hint: Option<Value>,
}
// ─────────────────────────────────────────────────────────────────────────────
// ApiError wrapper
// ─────────────────────────────────────────────────────────────────────────────
/// An error that can be returned from any handler.
///
/// Implements [`IntoResponse`] so it can be used directly as a handler return
/// type via `Result<T, ApiError>`.
#[derive(Debug)]
pub struct ApiError {
pub inner: XerjError,
pub request_id: Option<String>,
pub hint: Option<Value>,
}
impl ApiError {
pub fn new(inner: XerjError) -> Self {
Self {
inner,
request_id: None,
hint: None,
}
}
pub fn with_request_id(mut self, id: impl Into<String>) -> Self {
self.request_id = Some(id.into());
self
}
/// Attach an actionable `_xerj` recovery hint (see [`EsErrorResponse`]).
/// Additive only — never changes `error.type` / `error.reason` / status.
pub fn with_hint(mut self, hint: Value) -> Self {
self.hint = Some(hint);
self
}
}
impl From<XerjError> for ApiError {
fn from(e: XerjError) -> Self {
Self::new(e)
}
}
impl ApiError {
/// ES-compatible error body as a plain `Value`, for contexts that never
/// go through axum's `Response` type — e.g. storing the `response` of a
/// completed `_tasks/{id}` entry for a detached background task.
pub fn into_value(self) -> Value {
let (_, body) = self.into_parts();
serde_json::to_value(body).unwrap_or_else(|_| json!({}))
}
fn into_parts(self) -> (StatusCode, EsErrorResponse) {
let mut status_code = self.inner.http_status();
// ES parity: an explicit write/metadata block is 403
// (`FORBIDDEN/…/cluster_block_exception`), but the disk *flood-stage*
// block (`read_only_allow_delete`) is rejected with HTTP 429
// (`TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark`).
// Both keep the `cluster_block_exception` type; only the status differs.
if let XerjError::IndexBlocked { block_type, .. } = &self.inner {
if block_type.contains("read_only_allow_delete") {
status_code = 429;
}
}
let mut error_type = xerj_error_type(&self.inner);
// ES wraps mapping/query errors with a specific phrasing in `reason`;
// our Display impl adds a "invalid mapping:" / "invalid query:" prefix
// that doesn't match the published shape. Strip it for compat.
let reason = match &self.inner {
XerjError::InvalidMapping { reason } => reason.clone(),
XerjError::InvalidQuery { reason } => reason.clone(),
other => other.to_string(),
};
// Try to extract index name for root_cause annotation.
let index_name = extract_index_name(&self.inner);
// ES date-resolution errors from the range parser (invalid `format`
// pattern, value that fails an explicit format, malformed date
// math). The query crate's Display wraps them as
// `parse error: <msg>`; strip that so the reason matches ES
// byte-for-byte, and surface ES's exception types
// (`illegal_argument_exception` for a bad format string,
// `parse_exception` in root_cause for unparseable values/math).
let mut reason = reason;
let mut date_root: Option<&'static str> = None;
{
let stripped = reason.strip_prefix("parse error: ").unwrap_or(&reason);
if stripped.starts_with("Invalid format: [") {
reason = stripped.to_string();
error_type = "illegal_argument_exception".into();
status_code = 400;
date_root = Some("illegal_argument_exception");
} else if stripped.starts_with("failed to parse date field [")
|| stripped.starts_with("operator not supported for date math [")
{
reason = stripped.to_string();
status_code = 400;
date_root = Some("parse_exception");
}
}
// ES specific-case: `failed to create query:` comes from shard-
// level query builders and reports `query_shard_exception` in
// root_cause while keeping the outer wrapper as its usual type.
let root_type = if let Some(rt) = date_root {
rt.to_string()
} else if reason.starts_with("failed to create query:") {
"query_shard_exception".to_string()
} else if reason.starts_with("No mapping found for") {
// #437: a sort field with no mapping is a shard-level query-
// build failure in real ES too, wrapped the same way as
// `failed to create query:` above — `query_shard_exception`
// in root_cause, outer wrapper unchanged.
"query_shard_exception".to_string()
} else if reason.starts_with("function score query returned an invalid score:") {
// ES validates function_score results and raises
// `illegal_argument_exception` with a 400 status when a
// function produces a non-finite or negative score
// (e.g. ln1p on qty=-1 → ln(0) = -∞).
error_type = "illegal_argument_exception".into();
status_code = 400;
"illegal_argument_exception".to_string()
} else {
error_type.clone()
};
// ES decorates `index_not_found_exception` with
// `resource.type`/`resource.id`/`index_uuid` and repeats `index` +
// `reason` at the top level, phrasing the reason as
// `no such index [name]`. Only apply this when the name is a real
// index name — several other 404s reuse this variant to carry a
// sentence (e.g. "index template [x] missing"), which must keep its
// existing shape. (RC4 Wave-3 item 4f.)
let (res_type, res_id, res_uuid, top_index) = match &self.inner {
XerjError::IndexNotFound { .. } => match index_name.as_deref() {
Some(n) if is_plain_index_name(n) => {
reason = format!("no such index [{n}]");
(
Some("index_or_alias".to_string()),
Some(n.to_string()),
Some("_na_".to_string()),
Some(n.to_string()),
)
}
_ => (None, None, None, None),
},
// A rejected name is not a mapping problem. ES puts the attempted
// name and `index_uuid: "_na_"` on `invalid_index_name_exception`
// and leaves the reason as the name rule that failed.
XerjError::InvalidIndexName { index, .. } => {
(None, None, Some("_na_".to_string()), Some(index.clone()))
}
_ => (None, None, None, None),
};
let http_status =
StatusCode::from_u16(status_code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
let root_cause = vec![EsRootCause {
error_type: root_type,
reason: reason.clone(),
resource_type: res_type.clone(),
resource_id: res_id.clone(),
index_uuid: res_uuid.clone(),
index: index_name,
}];
let body = EsErrorResponse {
error: EsErrorBody {
root_cause,
error_type,
reason,
resource_type: res_type,
resource_id: res_id,
index_uuid: res_uuid,
index: top_index,
request_id: self.request_id,
},
status: status_code,
xerj_hint: self.hint,
};
(http_status, body)
}
}
impl IntoResponse for ApiError {
fn into_response(self) -> Response {
let (http_status, body) = self.into_parts();
(http_status, Json(body)).into_response()
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Helpers
// ─────────────────────────────────────────────────────────────────────────────
/// Map a [`XerjError`] to an ES exception type string.
///
/// The returned strings match the `type` field in real ES error responses so
/// that existing ES clients, dashboards, and alerting rules can handle xerj
/// errors without modification.
///
/// Mapping table:
///
/// | `XerjError` variant | ES exception type | HTTP status |
/// |---|---|---|
/// | `IndexNotFound` | `index_not_found_exception` | 404 |
/// | `IndexAlreadyExists` | `resource_already_exists_exception` | 409 |
/// | `InvalidIndexName` | `invalid_index_name_exception` | 400 |
/// | `IndexUnavailable` | `no_shard_available_action_exception` | 503 |
/// | `DocumentNotFound` | `document_missing_exception` | 404 |
/// | `InvalidMapping` | `mapper_parsing_exception` | 400 |
/// | `InvalidQuery` | `search_phase_execution_exception` | 400 |
/// | `StorageError` / `WalError` | `store_exception` | 500 |
/// | `SerializationError` | `json_parse_exception` | 500 |
/// | `ConfigError` | `action_request_validation_exception` | 400 |
/// | `AuthError` | `security_exception` | 401 |
/// | `TlsError` | `connect_exception` | 500 |
/// | `EmbeddingError` | `circuit_breaking_exception` | 500 |
/// | `ResourceExhausted` | `es_rejected_execution_exception` | 429 |
/// | `CircuitBreaking` | `circuit_breaking_exception` | 429 |
/// | `VersionConflict` | `version_conflict_engine_exception` | 409 |
/// | `ResultWindowTooLarge` | `illegal_argument_exception` | 400 |
/// | `IndexBlocked` | `cluster_block_exception` | 403 |
/// | `ClusterUnavailable` | `master_not_discovered_exception` or `cluster_unavailable_exception` | 503 |
/// | `Internal` | `internal_server_error_exception` | 500 |
fn xerj_error_type(e: &XerjError) -> String {
match e {
// ── Index lifecycle ───────────────────────────────────────────────
XerjError::IndexNotFound { .. } => "index_not_found_exception",
XerjError::IndexAlreadyExists { .. } => "resource_already_exists_exception",
XerjError::InvalidIndexName { .. } => "invalid_index_name_exception",
// The index exists; its only copy cannot be opened. ES reports an
// existing-but-unallocated index this way, so dashboards that already
// understand a red shard understand this too.
XerjError::IndexUnavailable { .. } => "no_shard_available_action_exception",
// ── Document operations ───────────────────────────────────────────
XerjError::DocumentNotFound { .. } => "document_missing_exception",
// ── Mapping / schema ──────────────────────────────────────────────
XerjError::InvalidMapping { .. } => "mapper_parsing_exception",
// ── Query parsing / execution ─────────────────────────────────────
XerjError::InvalidQuery { .. } => "search_phase_execution_exception",
// ── Storage layer ─────────────────────────────────────────────────
XerjError::StorageError { .. } | XerjError::WalError { .. } => "store_exception",
// ── Serialization ─────────────────────────────────────────────────
XerjError::SerializationError { .. } => "json_parse_exception",
XerjError::InvalidDocumentJson { .. } => "json_parse_exception",
// ── Configuration ─────────────────────────────────────────────────
XerjError::ConfigError { .. } => "action_request_validation_exception",
XerjError::ClusterStateUnavailable => "cluster_state_unavailable",
// ── Auth ──────────────────────────────────────────────────────────
XerjError::AuthError { .. } => "security_exception",
// ── TLS ───────────────────────────────────────────────────────────
XerjError::TlsError { .. } => "connect_exception",
// ── Embedding / AI ────────────────────────────────────────────────
XerjError::EmbeddingError { .. } => "circuit_breaking_exception",
// ── Resource limits ───────────────────────────────────────────────
XerjError::ResourceExhausted { .. } => "es_rejected_execution_exception",
// ── Circuit breaker (parent memory breaker) ───────────────────────
XerjError::CircuitBreaking { .. } => "circuit_breaking_exception",
// ── Optimistic concurrency ────────────────────────────────────────
XerjError::VersionConflict { .. } => "version_conflict_engine_exception",
// ── Result window ─────────────────────────────────────────────────
XerjError::ResultWindowTooLarge { .. } => "illegal_argument_exception",
// ── Index blocks ──────────────────────────────────────────────────
XerjError::IndexBlocked { .. } => "cluster_block_exception",
// No leader is the ES "master not discovered" case. Any other reason
// (timeout, leadership lost, shutting down) is a generic 503: the
// write was not acknowledged and was not applied on this node.
XerjError::ClusterUnavailable { reason } => {
if reason.contains("no elected raft leader") {
"master_not_discovered_exception"
} else {
"cluster_unavailable_exception"
}
}
// ── Catch-all ─────────────────────────────────────────────────────
XerjError::Internal { .. } => "internal_server_error_exception",
}
.to_string()
}
/// Extract the index name from an error, when available, for the ES
/// `root_cause[].index` field. This lets clients identify which index
/// triggered the error without parsing the human-readable reason string.
fn extract_index_name(e: &XerjError) -> Option<String> {
match e {
XerjError::IndexNotFound { name } | XerjError::IndexAlreadyExists { name } => {
Some(name.clone())
}
XerjError::InvalidIndexName { index, .. } => Some(index.clone()),
XerjError::DocumentNotFound { index, .. } => Some(index.clone()),
XerjError::IndexBlocked { index, .. } | XerjError::IndexUnavailable { index, .. } => {
Some(index.clone())
}
_ => None,
}
}
/// Whether a string is a plausible concrete index/alias name rather than one
/// of the sentence-style messages some 404s smuggle through `IndexNotFound`
/// (e.g. "index template [x] missing"). ES index names cannot contain spaces
/// or brackets, so those characters reliably distinguish the two — only real
/// names receive the `resource.*` / `no such index [name]` ES treatment.
fn is_plain_index_name(name: &str) -> bool {
!name.is_empty() && !name.contains([' ', '[', ']'])
}
// ─────────────────────────────────────────────────────────────────────────────
// Native API error response (with request_id, timing)
// ─────────────────────────────────────────────────────────────────────────────
/// A native xerj error response body (richer than the ES format).
#[derive(Debug, Serialize)]
pub struct NativeErrorResponse {
pub error: String,
pub reason: String,
pub status: u16,
pub request_id: Option<String>,
pub took_ms: u64,
}
/// Convenience to build a native error response.
pub fn native_error(
e: XerjError,
request_id: Option<&str>,
took_ms: u64,
) -> (StatusCode, axum::Json<NativeErrorResponse>) {
let status_code = e.http_status();
let http_status =
StatusCode::from_u16(status_code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
let body = NativeErrorResponse {
error: xerj_error_type(&e),
reason: e.to_string(),
status: status_code,
request_id: request_id.map(str::to_owned),
took_ms,
};
(http_status, axum::Json(body))
}
#[cfg(test)]
mod raw_document_error_tests {
use super::*;
#[test]
fn invalid_document_json_renders_registered_actionable_400() {
let reason = "invalid raw JSON for document [row-17] at one-based batch position 17: \
trailing characters at line 1 column 9. Fix: replace that document body \
with exactly one complete UTF-8 JSON value, then retry the batch. Related \
help: `xerj index --help` and https://xerj.org/llms.txt";
let (status, body) = ApiError::new(XerjError::invalid_document_json(reason)).into_parts();
assert_eq!(status, StatusCode::BAD_REQUEST);
assert_eq!(body.error.error_type, "json_parse_exception");
assert_eq!(body.error.root_cause[0].error_type, "json_parse_exception");
assert!(body.error.reason.contains("document [row-17]"));
assert!(body.error.reason.contains("batch position 17"));
assert!(body.error.reason.contains("Fix:"));
assert!(body.error.reason.contains("Related help:"));
}
}