Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

HttpServerError unstable

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.

13 exports Since v4.0.0 Source

Error Handling

causeResponse

unstable
Since v4.0.0

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 HttpServerResponse values are used directly, and pure interrupts produce either 499 for client aborts or 503 for server aborts.

Signature

declare function causeResponse<E>(cause: Cause<E>): Effect<readonly [HttpServerResponse, Cause<E>]>

causeResponseStripped

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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 unstable
Since v4.0.0

Reason carried by an HttpServerError, either a request-level error or a response-level error.

Signature

type HttpServerErrorReason = RequestError | ResponseError

InternalError

unstable
Since v4.0.0

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 unstable
Since v4.0.0

Union of errors that are tied directly to an incoming server request.

Signature

type RequestError = RequestParseError | RouteNotFound | InternalError

RequestParseError

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Returns true when the supplied value is an HttpServerError.

Signature

declare function isHttpServerError(u: unknown): u is HttpServerError

Services

ClientAbort

unstable
Since v4.0.0

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>;
}