Skip to content

HttpClient

Provides the service used to run outgoing HTTP requests.

HttpClient executes immutable HttpClientRequest values and returns HttpClientResponse values. Keeping HTTP behind this service lets programs, tests, and generated API clients use the same request model without depending on one concrete platform transport. This module includes request accessors, constructors and layers, request and response transformations, status filtering, retries, rate limiting, cookies, redirect handling, scoped request abortion, and tracing support.

43 exports Added in v4.0.0 Source

Accessors

del

Added in v4.0.0 Source

Executes a DELETE request using the HttpClient service from the environment.

Signature

declare const del: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

execute

Added in v4.0.0 Source

Executes a prebuilt HttpClientRequest using the HttpClient service from the environment.

Signature

declare const execute: (
  request: HttpClientRequest.HttpClientRequest,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

get

Added in v4.0.0 Source

Executes a GET request using the HttpClient service from the environment.

Signature

declare const get: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

options

Added in v4.0.0 Source

Executes an OPTIONS request using the HttpClient service from the environment.

Signature

declare const options: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

patch

Added in v4.0.0 Source

Executes a PATCH request using the HttpClient service from the environment.

Signature

declare const patch: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

post

Added in v4.0.0 Source

Executes a POST request using the HttpClient service from the environment.

Signature

declare const post: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

put

Added in v4.0.0 Source

Executes a PUT request using the HttpClient service from the environment.

Signature

declare const put: (
  url: string | URL,
  options?: HttpClientRequest.Options.NoUrl,
) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error.HttpClientError, HttpClient>;

Constructors

make

Added in v4.0.0 Source

Constructs an HttpClient from a low-level request runner.

Details

The runner receives the request, resolved URL, abort signal, and current fiber. The client wrapper handles URL construction failures, tracing and propagation, header redaction, and aborting non-scoped requests on interruption.

Signature

declare function make(
  f: (
    request: HttpClientRequest,
    url: URL,
    signal: AbortSignal,
    fiber: Fiber<HttpClientResponse, HttpClientError>,
  ) => Effect<HttpClientResponse, HttpClientError>,
): HttpClient;

makeWith

Added in v4.0.0 Source

Constructs an HttpClient.With from a preprocessing function and a postprocessing function.

Details

execute applies preprocessing to the request and then passes the resulting request effect to postprocessing.

Signature

declare function makeWith<E2, R2, E, R>(
  postprocess: (request: Effect<HttpClientRequest, E2, R2>) => Effect<HttpClientResponse, E, R>,
  preprocess: Preprocess<E2, R2>,
): With<E, R>;

Cookies

withCookiesRef

Added in v4.0.0 Source

Adds a Ref of cookies to the client for handling cookies across requests.

When to use

Use to add shared cookie storage to a client so response cookies are retained and sent by later requests.

Signature

declare const withCookiesRef: {
  (ref: Ref<Cookies>): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, ref: Ref<Cookies>): With<E, R>;
};

Error Handling

catchTag

Added in v4.0.0 Source

Handles client failures with one or more matching _tag values and returns a transformed client.

Signature

declare const catchTag: {
  <K extends string | readonly [Tags<E>, Tags<E>], E, E1, R1>(
    tag: K,
    f: (
      e: ExtractTag<NoInfer<E>, K extends readonly [string, string] ? K[number] : K>,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): <R>(
    self: With<E, R>,
  ) => With<E1 | ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>, R1 | R>;
  <R, E, K extends string | readonly [Tags<E>, Tags<E>], R1, E1>(
    self: With<E, R>,
    tag: K,
    f: (
      e: ExtractTag<E, K extends readonly [string, string] ? K[number] : K>,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): With<E1 | ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>, R | R1>;
};

catchTags

Added in v4.0.0 Source

Handles client failures by matching their _tag values against a case map.

Signature

declare const catchTags: {
  <
    E,
    Cases extends
      | {
          [K in string]: (
            error: Extract<
              E,
              {
                _tag: K;
              }
            >,
          ) => Effect<HttpClientResponse, any, any>;
        }
      | ({
          [K in string]: (
            error: Extract<
              E,
              {
                _tag: K;
              }
            >,
          ) => Effect<HttpClientResponse, any, any>;
        } & { [K in number | symbol]: never }),
  >(
    cases: Cases,
  ): <R>(self: With<E, R>) => With<
    | Exclude<
        E,
        {
          _tag: keyof Cases;
        }
      >
    | {
        [K in string | number | symbol]: Cases[K] extends (
          ...args: Array<any>
        ) => Effect<any, E, any>
          ? E
          : never;
      }[keyof Cases],
    | R
    | {
        [K in string | number | symbol]: Cases[K] extends (
          ...args: Array<any>
        ) => Effect<any, any, R>
          ? R
          : never;
      }[keyof Cases]
  >;
  <
    E extends {
      _tag: string;
    },
    R,
    Cases extends
      | {
          [K in string]: (
            error: Extract<
              E,
              {
                _tag: K;
              }
            >,
          ) => Effect<HttpClientResponse, any, any>;
        }
      | ({
          [K in string]: (
            error: Extract<
              E,
              {
                _tag: K;
              }
            >,
          ) => Effect<HttpClientResponse, any, any>;
        } & { [K in number | symbol]: never }),
  >(
    self: With<E, R>,
    cases: Cases,
  ): With<
    | Exclude<
        E,
        {
          _tag: keyof Cases;
        }
      >
    | {
        [K in string | number | symbol]: Cases[K] extends (
          ...args: Array<any>
        ) => Effect<any, E, any>
          ? E
          : never;
      }[keyof Cases],
    | R
    | {
        [K in string | number | symbol]: Cases[K] extends (
          ...args: Array<any>
        ) => Effect<any, any, R>
          ? R
          : never;
      }[keyof Cases]
  >;
};

retry

Added in v4.0.0 Source

Retries the request based on a provided schedule or policy.

Signature

declare const retry: {
  <E, O extends NoExcessProperties<Options<E>, O>>(
    options: O,
  ): <R>(self: With<E, R>) => With<
    O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer _R>;
    }
      ? _E | E
      : O extends {
            times: number;
          }
        ? E
        : O extends {
              until: Predicate.Refinement<E, infer E2>;
            }
          ? E2
          : E | O extends {
                while: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>;
              }
            ? E
            : never | O extends {
                  until: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>;
                }
              ? E
              : never,
    R | O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer R>;
    }
      ? R
      : never | O extends {
            while: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>;
          }
        ? R
        : never | O extends {
              until: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>;
            }
          ? R
          : never
  >;
  <B, E, ES, R1>(
    policy: Schedule<B, NoInfer<E>, ES, R1>,
  ): <R>(self: With<E, R>) => With<E | ES, R1 | R>;
  <E, R, O extends NoExcessProperties<Options<E>, O>>(
    self: With<E, R>,
    options: O,
  ): With<
    O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer _R>;
    }
      ? _E | E
      : O extends {
            times: number;
          }
        ? E
        : O extends {
              until: Predicate.Refinement<E, infer E2>;
            }
          ? E2
          : E | O extends {
                while: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>;
              }
            ? E
            : never | O extends {
                  until: (...args: Array<any>) => Effect.Effect<infer _A, infer E, infer _R>;
                }
              ? E
              : never,
    R | O extends {
      schedule: Schedule.Schedule<infer _O, infer _I, infer _E, infer R>;
    }
      ? R
      : never | O extends {
            while: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>;
          }
        ? R
        : never | O extends {
              until: (...args: Array<any>) => Effect.Effect<infer _A, infer _E, infer R>;
            }
          ? R
          : never
  >;
  <E, R, B, ES, R1>(self: With<E, R>, policy: Schedule<B, E, ES, R1>): With<E | ES, R | R1>;
};

retryTransient

Added in v4.0.0 Source

Retries common transient errors, such as rate limiting, timeouts or network issues.

When to use

Use to focus on retrying errors, transient responses, or both.

Details

Specifying a while predicate allows you to consider other errors as transient, and is ignored in "response-only" mode.

Signature

declare const retryTransient: {
  <
    E,
    B = never,
    ES = never,
    R1 = never,
    RetryOn extends "errors-only" | "response-only" | "errors-and-responses" =
      | "errors-only"
      | "response-only"
      | "errors-and-responses",
    Input = RetryOn extends "errors-only"
      ? E
      : RetryOn extends "response-only"
        ? HttpClientResponse
        : HttpClientResponse | E,
  >(options: {
    readonly retryOn?: RetryOn;
    readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, ES, R1>;
    readonly times?: number;
    readonly while?: Predicate.Predicate<NoInfer<E | ES>>;
  }): <R>(self: With<E, R>) => With<E | ES, R1 | R>;
  <
    E,
    R,
    B = never,
    ES = never,
    R1 = never,
    RetryOn extends "errors-only" | "response-only" | "errors-and-responses" =
      | "errors-only"
      | "response-only"
      | "errors-and-responses",
    Input = RetryOn extends "errors-only"
      ? E
      : RetryOn extends "response-only"
        ? HttpClientResponse
        : HttpClientResponse | E,
  >(
    self: With<E, R>,
    options: {
      readonly retryOn?: RetryOn;
      readonly schedule?: Schedule.Schedule<B, NoInfer<Input>, ES, R1>;
      readonly times?: number;
      readonly while?: Predicate.Predicate<NoInfer<E | ES>>;
    },
  ): With<E | ES, R | R1>;
  <B, E, ES = never, R1 = never>(
    options: Schedule<B, NoInfer<HttpClientResponse | E>, ES, R1>,
  ): <R>(self: With<E, R>) => With<E | ES, R1 | R>;
  <E, R, B, ES = never, R1 = never>(
    self: With<E, R>,
    options: Schedule<B, NoInfer<HttpClientResponse | E>, ES, R1>,
  ): With<E | ES, R | R1>;
};

Filtering

filterOrElse

Added in v4.0.0 Source

Filters the result of a response, or runs an alternative effect if the predicate fails.

Signature

declare const filterOrElse: {
  <B extends HttpClientResponse, E2, R2>(
    refinement: Refinement<HttpClientResponse, B>,
    orElse: (
      response: EqualsWith<
        HttpClientResponse,
        B,
        HttpClientResponse,
        Exclude<HttpClientResponse, B>
      >,
    ) => Effect<HttpClientResponse, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E2, R2>(
    predicate: Predicate<HttpClientResponse>,
    orElse: (response: HttpClientResponse) => Effect<HttpClientResponse, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, B extends HttpClientResponse, E2, R2>(
    self: With<E, R>,
    refinement: Refinement<HttpClientResponse, B>,
    orElse: (
      response: EqualsWith<
        HttpClientResponse,
        B,
        HttpClientResponse,
        Exclude<HttpClientResponse, B>
      >,
    ) => Effect<HttpClientResponse, E2, R2>,
  ): With<E | E2, R | R2>;
  <E, R, E2, R2>(
    self: With<E, R>,
    predicate: Predicate<HttpClientResponse>,
    orElse: (response: HttpClientResponse) => Effect<HttpClientResponse, E2, R2>,
  ): With<E | E2, R | R2>;
};

filterOrFail

Added in v4.0.0 Source

Filters successful responses, or fails with the error produced by orFailWith when the predicate does not match.

Signature

declare const filterOrFail: {
  <B extends HttpClientResponse, E2>(
    refinement: Refinement<HttpClientResponse, B>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R>;
  <E2>(
    predicate: Predicate<HttpClientResponse>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R>;
  <E, R, B extends HttpClientResponse, E2>(
    self: With<E, R>,
    refinement: Refinement<HttpClientResponse, B>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): With<E | E2, R>;
  <E, R, E2>(
    self: With<E, R>,
    predicate: Predicate<HttpClientResponse>,
    orFailWith: (response: HttpClientResponse) => E2,
  ): With<E | E2, R>;
};

filterStatus

Added in v4.0.0 Source

Filters responses by HTTP status code.

Signature

declare const filterStatus: {
  (f: (status: number) => boolean): <E, R>(self: With<E, R>) => With<HttpClientError | E, R>;
  <E, R>(self: With<E, R>, f: (status: number) => boolean): With<HttpClientError | E, R>;
};

filterStatusOk

Added in v4.0.0 Source

Filters responses that return a 2xx status code.

Signature

declare const filterStatusOk: <E, R>(
  self: HttpClient.With<E, R>,
) => HttpClient.With<E | Error.HttpClientError, R>;

Guards

isHttpClient

Added in v4.0.0 Source

Returns true if the provided value is an HttpClient.

Signature

declare function isHttpClient(u: unknown): u is HttpClient;

Layers

layerMergedContext

Added in v4.0.0 Source

Creates an HttpClient layer and merges the layer construction context into client response effects.

Signature

declare function layerMergedContext<E, R>(
  effect: Effect<HttpClient, E, R>,
): Layer<HttpClient, E, R>;

Mapping

mapRequest

Added in v4.0.0 Source

Appends a transformation of the request object before sending it.

Signature

declare const mapRequest: {
  (f: (a: HttpClientRequest) => HttpClientRequest): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, f: (a: HttpClientRequest) => HttpClientRequest): With<E, R>;
};

mapRequestEffect

Added in v4.0.0 Source

Appends an effectful transformation of the request object before sending it.

Signature

declare const mapRequestEffect: {
  <E2, R2>(
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, E2, R2>(
    self: With<E, R>,
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): With<E | E2, R | R2>;
};

mapRequestInput

Added in v4.0.0 Source

Prepends a transformation of the request object before sending it.

Signature

declare const mapRequestInput: {
  (f: (a: HttpClientRequest) => HttpClientRequest): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, f: (a: HttpClientRequest) => HttpClientRequest): With<E, R>;
};

mapRequestInputEffect

Added in v4.0.0 Source

Prepends an effectful transformation of the request object before sending it.

Signature

declare const mapRequestInputEffect: {
  <E2, R2>(
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, E2, R2>(
    self: With<E, R>,
    f: (a: HttpClientRequest) => Effect<HttpClientRequest, E2, R2>,
  ): With<E | E2, R | R2>;
};

transform

Added in v4.0.0 Source

Transforms a client by wrapping the response effect for each request.

Details

The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.

Signature

declare const transform: {
  <E, R, E1, R1>(
    f: (
      effect: Effect<HttpClientResponse, E, R>,
      request: HttpClientRequest,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): (self: With<E, R>) => With<E | E1, R | R1>;
  <E, R, E1, R1>(
    self: With<E, R>,
    f: (
      effect: Effect<HttpClientResponse, E, R>,
      request: HttpClientRequest,
    ) => Effect<HttpClientResponse, E1, R1>,
  ): With<E | E1, R | R1>;
};

transformResponse

Added in v4.0.0 Source

Transforms a client by applying an effectful transformation to each response effect.

Signature

declare const transformResponse: {
  <E, R, E1, R1>(
    f: (effect: Effect<HttpClientResponse, E, R>) => Effect<HttpClientResponse, E1, R1>,
  ): (self: With<E, R>) => With<E1, R1>;
  <E, R, E1, R1>(
    self: With<E, R>,
    f: (effect: Effect<HttpClientResponse, E, R>) => Effect<HttpClientResponse, E1, R1>,
  ): With<E1, R1>;
};

Models

HttpClient interface

Added in v4.0.0 Source

HTTP client whose requests produce HttpClientResponse values and can fail with HttpClientError.

Signature

interface HttpClient extends With<Error.HttpClientError> {}

Other

catch

Source

Signature

declare const catch: {
  <E, E2, R2>(f: (e: E) => Effect<HttpClientResponse, E2, R2>): <R>(self: With<E, R>) => With<E2, R2 | R>;
  <E, R, A2, E2, R2>(self: With<E, R>, f: (e: E) => Effect<A2, E2, R2>): With<E2, R | R2>;
}

HttpClient

Added in v4.0.0 Source

Namespace containing type-level members associated with HttpClient.

Retry

Added in v4.0.0 Source

Namespace containing type-level helpers for retrying HTTP clients.

WithRateLimiter

Added in v4.0.0 Source

Namespace containing configuration types for withRateLimiter.

Rate Limiting

withRateLimiter

Added in v4.0.0 Source

Applies request rate limiting using the RateLimiter service.

Details

It can update limits by inspecting common rate limit response headers and automatically retries HTTP 429 responses (or HttpClientError values wrapping a 429 response) by forcing the retry back through the limiter.

Signature

declare const withRateLimiter: {
  (options: Options): <E, R>(self: With<E, R>) => With<E | RateLimiterError, R>;
  <E, R>(self: With<E, R>, options: Options): With<E | RateLimiterError, R>;
};

Redirects

followRedirects

Added in v4.0.0 Source

Enables following HTTP redirects up to a specified number of times.

Signature

declare const followRedirects: {
  (maxRedirects?: number): <E, R>(self: With<E, R>) => With<E, R>;
  <E, R>(self: With<E, R>, maxRedirects?: number): With<E, R>;
};

Resource Management

withScope

Added in v4.0.0 Source

Attaches the lifetime of the HttpClientRequest to a Scope.

Signature

declare function withScope<E, R>(self: With<E, R>): With<E, Scope | R>;

Sequencing

tap

Added in v4.0.0 Source

Performs an additional effect after a successful request.

Signature

declare const tap: {
  <_, E2, R2>(
    f: (response: HttpClientResponse) => Effect<_, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, _, E2, R2>(
    self: With<E, R>,
    f: (response: HttpClientResponse) => Effect<_, E2, R2>,
  ): With<E | E2, R | R2>;
};

tapError

Added in v4.0.0 Source

Performs an additional effect after an unsuccessful request.

Signature

declare const tapError: {
  <_, E, E2, R2>(
    f: (e: NoInfer<E>) => Effect<_, E2, R2>,
  ): <R>(self: With<E, R>) => With<E | E2, R2 | R>;
  <E, R, _, E2, R2>(
    self: With<E, R>,
    f: (e: NoInfer<E>) => Effect<_, E2, R2>,
  ): With<E | E2, R | R2>;
};

tapRequest

Added in v4.0.0 Source

Performs an additional effect on the request before sending it.

Signature

declare const tapRequest: {
  <_, E2, R2>(
    f: (a: HttpClientRequest) => Effect<_, E2, R2>,
  ): <E, R>(self: With<E, R>) => With<E2 | E, R2 | R>;
  <E, R, _, E2, R2>(
    self: With<E, R>,
    f: (a: HttpClientRequest) => Effect<_, E2, R2>,
  ): With<E | E2, R | R2>;
};

Services

HttpClient

Added in v4.0.0 Source

Service tag for the default outgoing HTTP client service.

When to use

Use to provide the default outgoing HTTP client service used by request accessors such as execute, get, and post.

Signature

declare const HttpClient: Service<HttpClient, HttpClient>;

SpanNameGenerator

Added in v4.0.0 Source

Context reference for generating the span name used for outgoing client request spans.

Signature

declare const SpanNameGenerator: Reference<(request: HttpClientRequest) => string>;

TracerDisabledWhen

Added in v4.0.0 Source

Context reference for a predicate that disables client-side tracing for matching outgoing requests.

Signature

declare const TracerDisabledWhen: Reference<Predicate<HttpClientRequest>>;

TracerHeaderFilter

Added in v4.0.0 Source

Context reference for filtering request and response headers added to client spans.

Signature

declare const TracerHeaderFilter: Reference<
  (headerName: string, phase: "request" | "response") => boolean
>;

TracerPropagationEnabled

Added in v4.0.0 Source

Context reference that controls whether outgoing client spans are propagated to request headers.

Signature

declare const TracerPropagationEnabled: Reference<boolean>;