pub struct HttpError {
pub status_code: ErrorStatusCode,
pub error_code: Option<String>,
pub external_message: String,
pub internal_message: String,
pub headers: Option<Box<HeaderMap>>,
}Expand description
HttpError represents an error generated as part of handling an API
request. When these bubble up to the top of the request handling stack
(which is most of the time that they’re generated), these are turned into an
HTTP response, which includes:
- a status code, which is likely either 400-level (indicating a client error, like bad input) or 500-level (indicating a server error).
- a structured (JSON) body, which includes:
- a string error code, which identifies the underlying error condition so that clients can potentially make programmatic decisions based on the error type
- a string error message, which is the human-readable summary of the issue, intended to make sense for API users (i.e., not API server developers)
- optionally: additional metadata describing the issue. For a validation error, this could include information about which parameter was invalid and why. This should conform to a schema associated with the error code.
It’s easy to go overboard with the error codes and metadata. Generally, we should avoid creating specific codes and metadata unless there’s a good reason for a client to care.
Besides that, HttpErrors also have an internal error message, which may
differ from the error message that gets reported to users. For example, if
the request fails because an internal database is unreachable, the client may
just see “internal error”, while the server log would include more details
like “failed to acquire connection to database at 10.1.2.3”.
Fields§
§status_code: ErrorStatusCodeHTTP status code for this error
error_code: Option<String>Optional string error code for this error. Callers are advised to use an enum to populate this field.
external_message: StringError message to be sent to API client for this error
internal_message: StringError message recorded in the log for this error
headers: Option<Box<HeaderMap>>Headers that will be added to responses generated from this error.
Implementations§
Source§impl HttpError
impl HttpError
Sourcepub fn for_client_error(
error_code: Option<String>,
status_code: ClientErrorStatusCode,
message: String,
) -> Self
pub fn for_client_error( error_code: Option<String>, status_code: ClientErrorStatusCode, message: String, ) -> Self
Generates an HttpError for any 400-level client error with a custom
message used for both the internal and external message. The
expectation here is that for most 400-level errors, there’s no need for a
separate internal message.
Sourcepub fn for_internal_error(internal_message: String) -> Self
pub fn for_internal_error(internal_message: String) -> Self
Generates an HttpError for a 500 “Internal Server Error” error with the
given internal_message for the internal message.
Generates an HttpError for a 503 “Service Unavailable” error with the
given internal_message for the internal message.
Sourcepub fn for_bad_request(error_code: Option<String>, message: String) -> Self
pub fn for_bad_request(error_code: Option<String>, message: String) -> Self
Generates a 400 “Bad Request” error with the given message used for
both the internal and external message. This is a convenience wrapper
around HttpError::for_client_error.
Sourcepub fn for_client_error_with_status(
error_code: Option<String>,
status_code: ClientErrorStatusCode,
) -> Self
pub fn for_client_error_with_status( error_code: Option<String>, status_code: ClientErrorStatusCode, ) -> Self
Generates an HttpError for the given HTTP status_code where the
internal and external messages for the error come from the standard label
for this status code (e.g., the message for status code 404 is “Not
Found”).
Sourcepub fn for_not_found(
error_code: Option<String>,
internal_message: String,
) -> Self
pub fn for_not_found( error_code: Option<String>, internal_message: String, ) -> Self
Generates an HttpError for a 404 “Not Found” error with a custom
internal message internal_message. The external message will be “Not
Found” (i.e., the standard label for status code 404).
Sourcepub fn headers_mut(&mut self) -> &mut HeaderMap
pub fn headers_mut(&mut self) -> &mut HeaderMap
Mutably borrow the http::HeaderMap associated with this error. If
there is no header map for this error, this method creates one.
Sourcepub fn add_header<K, V>(
&mut self,
name: K,
value: V,
) -> Result<&mut Self, Error>where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
pub fn add_header<K, V>(
&mut self,
name: K,
value: V,
) -> Result<&mut Self, Error>where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
Adds a header to the http::HeaderMap of headers to add to responses
generated from this error.
If this error does not already have a header map (self.header_map is
None), this method creates one.
§Returns
Ok(&mut Self)if the providednameandvalueare a valid header name and value, respectively.Err(http::Error)if the header name or value is invalid, or theHeaderMapis full.
Sourcepub fn with_header<K, V>(self, name: K, value: V) -> Result<Self, Error>where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
pub fn with_header<K, V>(self, name: K, value: V) -> Result<Self, Error>where
HeaderName: TryFrom<K>,
<HeaderName as TryFrom<K>>::Error: Into<Error>,
HeaderValue: TryFrom<V>,
<HeaderValue as TryFrom<V>>::Error: Into<Error>,
Adds a header to the http::HeaderMap of headers to add to responses
generated from this error, taking the error by value.
If this error does not already have a header map (self.header_map is
None), this method creates one.
Unlike HttpError::add_header, this method takes self by value,
allowing it to be chained to form an expression that returns an
HttpError. However, because this takes self by value, returning an
error for an invalid header name or value will discard the HttpError.
To avoid this, use HttpError::add_header instead.
§Returns
Ok(Self)if the providednameandvalueare a valid header name and value, respectively.Err(http::Error)if the header name or value is invalid, or theHeaderMapis full.
Sourcepub fn into_response(self, request_id: &str) -> Response<Body>
pub fn into_response(self, request_id: &str) -> Response<Body>
Generates an HTTP response for the given HttpError, using request_id
for the response’s request id.