HttpServerError
Describes failures raised while handling HTTP server requests.
HttpServerError covers failures that happen while accepting a request, matching a route, running a handler, or building and sending a response. Request-scoped failures keep the request that caused them, and response failures keep the response being produced. This module also includes helpers for turning failed causes or exits into HTTP responses and an annotation for interrupts caused by client aborts.
Error Handling
causeResponse
Signature
declare function causeResponse<E>(cause: Cause<E>): Effect<readonly [HttpServerResponse, Cause<E>]>;causeResponseStripped
Derives an HTTP response from a failed handler cause synchronously.
Details
If the cause contains a defect that is already an HttpServerResponse, that response is used and removed from the remaining cause. Otherwise the response defaults to 500.
Signature
declare function causeResponseStripped<E>(
cause: Cause<E>,
): readonly [HttpServerResponse, Option<Cause<E>>];exitResponse
Extracts the response from a successful handler exit, or derives a response from the failure cause.
Signature
declare function exitResponse<E>(exit: Exit<HttpServerResponse, E>): HttpServerResponse;Errors
HttpServerError
Tagged error for failures that occur while handling an HTTP server request.
Details
It wraps a HttpServerErrorReason, exposes the associated request and optional response, and can be converted to an HTTP response through the Respondable protocol.
Signature
declare class HttpServerError extends YieldableError<this> & {
readonly _tag: "HttpServerError";
} & Readonly<{
readonly reason: HttpServerErrorReason;
}> implements Respondable {
constructor(props: {
readonly reason: HttpServerErrorReason;
});
readonly "~effect/http/HttpServerError": "~effect/http/HttpServerError";
stack: string;
"~effect/ErrorReporter/ignore": boolean;
message: string;
request: HttpServerRequest;
response: HttpServerResponse | undefined;
"~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}HttpServerErrorReason type
Reason carried by an HttpServerError, either a request-level error or a response-level error.
Signature
type HttpServerErrorReason = RequestError | ResponseError;InternalError
Error describing an unexpected server-side failure while handling a request.
Details
When converted to a response it produces an empty 500 response.
Signature
declare class InternalError extends YieldableError<this> & {
readonly _tag: "InternalError";
} & Readonly<{
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
}> implements Respondable {
constructor(args: {
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
});
message: string;
methodAndUrl: string;
"~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}RequestError type
Union of errors that are tied directly to an incoming server request.
Signature
type RequestError = RequestParseError | RouteNotFound | InternalError;RequestParseError
Error describing a failure to parse or read an incoming request.
Details
When converted to a response it produces an empty 400 response.
Signature
declare class RequestParseError extends YieldableError<this> & {
readonly _tag: "RequestParseError";
} & Readonly<{
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
}> implements Respondable {
constructor(args: {
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
});
message: string;
methodAndUrl: string;
"~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}ResponseError
Error describing a failure related to an HTTP response.
Details
It carries the request and response involved in the failure. When converted to a response it produces an empty 500 response.
Signature
declare class ResponseError extends YieldableError<this> & {
readonly _tag: "ResponseError";
} & Readonly<{
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
readonly response: HttpServerResponse;
}> implements Respondable {
constructor(args: {
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
readonly response: HttpServerResponse;
});
message: string;
methodAndUrl: string;
"~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}RouteNotFound
Error indicating that no route matched the incoming request.
Details
When converted to a response it produces an empty 404 response, and it is ignored by the error reporter.
Signature
declare class RouteNotFound extends YieldableError<this> & {
readonly _tag: "RouteNotFound";
} & Readonly<{
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
}> implements Respondable {
constructor(args: {
readonly cause?: unknown;
readonly description?: string;
readonly request: HttpServerRequest;
});
readonly "~effect/ErrorReporter/ignore": true;
message: string;
methodAndUrl: string;
"~effect/http/HttpServerRespondable"(): Effect<HttpServerResponse, never, never>;
}ServeError
Error wrapping a low-level failure from the HTTP server implementation.
Signature
declare class ServeError extends YieldableError<this> & {
readonly _tag: "ServeError";
} & Readonly<{
readonly cause: unknown;
}> {
constructor(args: {
readonly cause: unknown;
});
}Guards
isHttpServerError
Returns true when the supplied value is an HttpServerError.
Signature
declare function isHttpServerError(u: unknown): u is HttpServerError;Services
ClientAbort
Context annotation used to mark an interrupt as caused by the client aborting the request.
Details
causeResponse uses this annotation to map a pure client abort to a 499 response instead of a server abort response.
Signature
declare class ClientAbort extends Shape<"effect/http/HttpServerError/ClientAbort", true, this> {
constructor(_: never);
static annotation: Context<StackTrace | ClientAbort>;
}
Converts a failed handler cause into the HTTP response that should be sent and the cause that should be reported.
Details
Respondable failures and defects can choose their own response, defects that are already
HttpServerResponsevalues are used directly, and pure interrupts produce either499for client aborts or503for server aborts.