Enum MiddlewareError 

pub enum MiddlewareError {
    Unauthenticated(String),
    Unauthorized(String),
    RateLimitExceeded {
        message: String,
        retry_after: Option<u64>,
    },
    InvalidRequest(String),
    Internal(String),
    Custom {
        code: String,
        message: String,
    },
    HttpChallenge {
        status: u16,
        www_authenticate: String,
        body: Option<String>,
    },
}

Errors that can occur during middleware execution

These errors are converted to McpError by the framework and then to JSON-RPC error responses. Middleware should use semantic error types rather than creating JSON-RPC errors directly.

Conversion Chain

MiddlewareError → McpError → JsonRpcError → HTTP/Lambda response

JSON-RPC Error Codes

Each error variant maps to a specific JSON-RPC error code (see error_codes):

• Unauthenticated → -32001 “Authentication required”
• Unauthorized → -32002 “Permission denied”
• RateLimitExceeded → -32003 “Rate limit exceeded”
• InvalidRequest → -32600 (standard Invalid Request)
• Internal → -32603 (standard Internal error)
• Custom{code, msg} → custom code from variant

Examples

use turul_http_mcp_server::middleware::{MiddlewareError, McpMiddleware, RequestContext, SessionInjection};
use turul_mcp_session_storage::SessionView;
use async_trait::async_trait;

struct ApiKeyAuth {
    valid_key: String,
}

#[async_trait]
impl McpMiddleware for ApiKeyAuth {
    async fn before_dispatch(
        &self,
        ctx: &mut RequestContext<'_>,
        _session: Option<&dyn SessionView>,
        _injection: &mut SessionInjection,
    ) -> Result<(), MiddlewareError> {
        let key = ctx.metadata()
            .get("api-key")
            .and_then(|v| v.as_str())
            .ok_or_else(|| MiddlewareError::Unauthorized("Missing API key".into()))?;

        if key != self.valid_key {
            return Err(MiddlewareError::Unauthorized("Invalid API key".into()));
        }

        Ok(())
    }
}

Variants

Unauthenticated(String)

Authentication required but not provided

Unauthorized(String)

Authentication provided but insufficient permissions

RateLimitExceeded

Rate limit exceeded

Fields

message: String

Human-readable message

retry_after: Option<u64>

Seconds until limit resets

InvalidRequest(String)

Request validation failed

Internal(String)

Internal middleware error (should not expose to client)

Custom

Custom error with code and message

Fields

code: String

Error code (for structured error handling)

message: String

Human-readable message

HttpChallenge

HTTP-level challenge response (401/403 with WWW-Authenticate header)

Used for OAuth 2.1 Bearer token challenges. This variant is handled exclusively at the transport level (pre-session phase) and produces a raw HTTP response — it NEVER reaches map_middleware_error_to_jsonrpc().

An unreachable!() guard in that function catches programming errors.

Fields

status: u16

HTTP status code (401 or 403)

www_authenticate: String

WWW-Authenticate header value (e.g., Bearer realm="mcp", resource_metadata="...")

body: Option<String>

Optional JSON error body

Implementations

impl MiddlewareError

pub fn unauthenticated(msg: impl Into<String>) -> Self

Create an unauthenticated error

pub fn unauthorized(msg: impl Into<String>) -> Self

Create an unauthorized error

pub fn rate_limit(msg: impl Into<String>, retry_after: Option<u64>) -> Self

Create a rate limit error

pub fn invalid_request(msg: impl Into<String>) -> Self

Create an invalid request error

pub fn internal(msg: impl Into<String>) -> Self

Create an internal error

pub fn custom(code: impl Into<String>, message: impl Into<String>) -> Self

Create a custom error

pub fn http_challenge(status: u16, www_authenticate: impl Into<String>) -> Self

Create an HTTP challenge error (401/403 with WWW-Authenticate header)

Used for OAuth 2.1 Bearer token challenges. Handled at transport level only.

pub fn http_challenge_with_body( status: u16, www_authenticate: impl Into<String>, body: impl Into<String>, ) -> Self

Create an HTTP challenge error with a response body

Trait Implementations

impl Clone for MiddlewareError

fn clone(&self) -> MiddlewareError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MiddlewareError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MiddlewareError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for MiddlewareError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for MiddlewareError

fn eq(&self, other: &MiddlewareError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for MiddlewareError