HttpClientError unstable

Typed failure model for Effect HTTP client operations.

HTTP clients wrap request construction, transport, status-code validation, and response decoding failures in HttpClientError. The wrapper keeps the failed request and the specific failure reason together, so callers can handle client failures uniformly while still matching on the reason _tag for retry policy, logging, metrics, and user-facing messages.

12 exports Since v4.0.0 Source

Errors

DecodeError

unstable

Since v4.0.0

Response error for failures while decoding an HTTP response body.

Signature

declare class DecodeError extends YieldableError<this> & {
  readonly _tag: "DecodeError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
  readonly response: HttpClientResponse;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
    readonly response: HttpClientResponse;
  });
  message: string;
  methodAndUrl: string;
}

EmptyBodyError

unstable

Since v4.0.0

Response error for operations that expected a response body but received an empty body.

Signature

declare class EmptyBodyError extends YieldableError<this> & {
  readonly _tag: "EmptyBodyError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
  readonly response: HttpClientResponse;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
    readonly response: HttpClientResponse;
  });
  message: string;
  methodAndUrl: string;
}

EncodeError

unstable

Since v4.0.0

Error describing failures while encoding an HTTP request body.

Signature

declare class EncodeError extends YieldableError<this> & {
  readonly _tag: "EncodeError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
  });
  message: string;
  methodAndUrl: string;
}

HttpClientError

unstable

Since v4.0.0

Error wrapper for HTTP client failures, exposing the failed request and the optional response through its reason.

Signature

declare class HttpClientError extends YieldableError<this> & {
  readonly _tag: "HttpClientError";
} & Readonly<{
  readonly reason: HttpClientErrorReason;
}> {
  constructor(props: {
    readonly reason: HttpClientErrorReason;
  });
  readonly "~effect/http/HttpClientError": "~effect/http/HttpClientError";
  message: string;
  request: HttpClientRequest;
  response: HttpClientResponse | undefined;
}

HttpClientErrorReason

type unstable

Since v4.0.0

Union of all specific failure reasons carried by HttpClientError.

Signature

type HttpClientErrorReason = RequestError | ResponseError

InvalidUrlError

unstable

Since v4.0.0

Error describing failures while constructing a URL from an HTTP client request.

Signature

declare class InvalidUrlError extends YieldableError<this> & {
  readonly _tag: "InvalidUrlError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
  });
  message: string;
  methodAndUrl: string;
}

RequestError

type unstable

Since v4.0.0

Union of HTTP client errors that occur before a response is available.

Signature

type RequestError = TransportError | EncodeError | InvalidUrlError

ResponseError

type unstable

Since v4.0.0

Union of HTTP client errors that include an HTTP response.

Signature

type ResponseError = StatusCodeError | DecodeError | EmptyBodyError

StatusCodeError

unstable

Since v4.0.0

Response error for HTTP responses rejected because of their status code.

Signature

declare class StatusCodeError extends YieldableError<this> & {
  readonly _tag: "StatusCodeError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
  readonly response: HttpClientResponse;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
    readonly response: HttpClientResponse;
  });
  message: string;
  methodAndUrl: string;
}

TransportError

unstable

Since v4.0.0

Error describing transport-level failures that occur while sending an HTTP request.

Signature

declare class TransportError extends YieldableError<this> & {
  readonly _tag: "TransportError";
} & Readonly<{
  readonly cause?: unknown;
  readonly description?: string;
  readonly request: HttpClientRequest;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly request: HttpClientRequest;
  });
  message: string;
  methodAndUrl: string;
}

Guards

isHttpClientError

unstable

Since v4.0.0

Returns true when a value is an HttpClientError.

Signature

declare function isHttpClientError(u: unknown): u is HttpClientError

Schemas

HttpClientErrorSchema

unstable

Since v4.0.0

Schema for serializable HTTP client errors, preserving the specific error kind and cause.

Signature

declare class HttpClientErrorSchema extends {
  readonly _tag: "HttpError";
  readonly cause?: unknown;
  readonly kind: "TransportError" | "EncodeError" | "InvalidUrlError" | "StatusCodeError" | "DecodeError" | "EmptyBodyError";
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "HttpError";
    readonly cause?: unknown;
    readonly kind: "TransportError" | "EncodeError" | "InvalidUrlError" | "StatusCodeError" | "DecodeError" | "EmptyBodyError";
  }, options?: MakeOptions]);
  static fromHttpClientError(error: HttpClientError): HttpClientErrorSchema;
}