Struct ConnectError 

pub struct ConnectError {
    pub code: ErrorCode,
    pub message: Option<String>,
    pub details: Vec<ErrorDetail>,
    /* private fields */
}

The Connect transport error DialError::Connect wraps, re-exported for the same reason ErrorCode is: an edge that maps a dial failure onto its own surface’s error taxonomy needs to name the type it is mapping from. A ConnectRPC error.

Fields

code: ErrorCode

The error code.

message: Option<String>

Human-readable error message.

details: Vec<ErrorDetail>

Additional error details.

Implementations

impl ConnectError

pub fn new(code: ErrorCode, message: impl Into<String>) -> ConnectError

Create a new error with the given code and message.

pub fn with_headers(self, headers: HeaderMap) -> ConnectError

Add response headers to be included in the error response.

pub fn with_trailers(self, trailers: HeaderMap) -> ConnectError

Add response trailers to be included in the error response.

pub fn response_headers(&self) -> &HeaderMap

Borrow the response headers. Returns an empty map if none were set.

pub fn trailers(&self) -> &HeaderMap

Borrow the response trailers. Returns an empty map if none were set.

pub fn response_headers_mut(&mut self) -> &mut HeaderMap

Mutably borrow the response headers, allocating an empty map if none were set.

pub fn trailers_mut(&mut self) -> &mut HeaderMap

Mutably borrow the response trailers, allocating an empty map if none were set.

pub fn set_response_headers(&mut self, headers: HeaderMap)

Replace the response headers. An empty map is stored as None.

pub fn set_trailers(&mut self, trailers: HeaderMap)

Replace the response trailers. An empty map is stored as None.

pub fn with_http_status(self, status: StatusCode) -> ConnectError

Set an HTTP status override for this error.

When set, this overrides the default HTTP status derived from the error code. This is useful for HTTP-level errors like 415 Unsupported Media Type.

pub fn unsupported_media_type(message: impl Into<String>) -> ConnectError

Create an error for unsupported media type (HTTP 415).

This is used when the client sends a content type that the server doesn’t support.

pub fn method_not_allowed(message: impl Into<String>) -> ConnectError

Create an error for method not allowed (HTTP 405).

This is used when the client uses an HTTP method other than POST.

pub fn canceled(message: impl Into<String>) -> ConnectError

Create a canceled error.

pub fn unknown(message: impl Into<String>) -> ConnectError

Create an unknown error.

pub fn invalid_argument(message: impl Into<String>) -> ConnectError

Create an invalid argument error.

pub fn deadline_exceeded(message: impl Into<String>) -> ConnectError

Create a deadline exceeded error.

pub fn not_found(message: impl Into<String>) -> ConnectError

Create a not found error.

pub fn already_exists(message: impl Into<String>) -> ConnectError

Create an already exists error.

pub fn permission_denied(message: impl Into<String>) -> ConnectError

Create a permission denied error.

pub fn resource_exhausted(message: impl Into<String>) -> ConnectError

Create a resource exhausted error.

pub fn failed_precondition(message: impl Into<String>) -> ConnectError

Create a failed precondition error.

pub fn aborted(message: impl Into<String>) -> ConnectError

Create an aborted error.

pub fn out_of_range(message: impl Into<String>) -> ConnectError

Create an out of range error.

pub fn unimplemented(message: impl Into<String>) -> ConnectError

Create an unimplemented error.

pub fn internal(message: impl Into<String>) -> ConnectError

Create an internal error.

pub fn unavailable(message: impl Into<String>) -> ConnectError

Create an unavailable error.

pub fn data_loss(message: impl Into<String>) -> ConnectError

Create a data loss error.

pub fn unauthenticated(message: impl Into<String>) -> ConnectError

Create an unauthenticated error.

pub fn with_detail(self, detail: ErrorDetail) -> ConnectError

Add an error detail.

pub fn http_status(&self) -> StatusCode

Get the HTTP status code for this error.

Returns the HTTP status override if set, otherwise derives it from the error code.

pub fn to_json(&self) -> Bytes

Encode this error as JSON bytes.

impl ConnectError

pub fn into_http_response( self, request_headers: &HeaderMap, ) -> Response<ConnectRpcBody>

Render this error as a complete HTTP response in the wire format matching the inbound request’s protocol.

This is the building block for tower::Layers that short-circuit a request (auth, rate limiting, validation) before it reaches ConnectRpcService. A layer cannot reuse the service’s internal error rendering, but still needs to produce a response that the calling client will decode as a structured error rather than a transport failure. Each protocol expects a different wire shape:

• Connect unary (application/proto, application/json, or absent — Connect GET requests carry no request body or Content-Type): a non-200 HTTP status with a JSON error body. Connect unary error bodies are spec-required JSON regardless of the request codec.
• Connect streaming (application/connect+{proto,json}): HTTP 200 with the error in an EndStreamResponse envelope.
• gRPC / gRPC-Web (application/grpc*): HTTP 200 with grpc-status and grpc-message trailers (as HTTP/2 trailers for gRPC, encoded in the body for gRPC-Web).

The protocol is detected from request_headers via Protocol::detect. When detection fails — an unrecognized Content-Type, or none at all — the Connect unary JSON shape is used, which is the most universally parseable fallback.

gRPC and gRPC-Web use the same framed wire shape for unary and streaming calls, so the trailers-only response is always correct regardless of the method’s cardinality.

Example

use connectrpc::ConnectError;

// Inside a tower::Service::call wrapping ConnectRpcService:
fn call(&mut self, req: http::Request<B>) -> Self::Future {
    if !self.is_authorized(&req) {
        let resp = ConnectError::permission_denied("access denied")
            .into_http_response(req.headers());
        return Box::pin(std::future::ready(Ok(resp)));
    }
    // ... call inner service ...
}

Trait Implementations

impl Clone for ConnectError

fn clone(&self) -> ConnectError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConnectError

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ConnectError

fn deserialize<__D>( __deserializer: __D, ) -> Result<ConnectError, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ConnectError

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

Formats the value using the given formatter.

impl Error for ConnectError

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 From<ConnectError> for DialError

fn from(source: ConnectError) -> Self

Converts to this type from the input type.

impl From<Error> for ConnectError

fn from(err: Error) -> ConnectError

Converts to this type from the input type.

impl From<Error> for ConnectError

Lets Response::try_with_header(..)? propagate naturally inside a handler.

fn from(err: Error) -> ConnectError

Converts to this type from the input type.

impl IntoResponse for ConnectError

fn into_response(self) -> Response<Body>

Create a response.

impl Serialize for ConnectError

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.