Error Types Overview | Effect Http Client

When working with HttpClient, you’ll encounter a small set of well-defined error types. Understanding them is essential for writing robust error handling code.

HttpClientError

HttpClientError is the single error class for all HTTP client errors. Every error from the client is an HttpClientError with _tag: "HttpClientError". What varies is the reason, which is a union of six tagged types, split into two categories: request errors (failures before the server responds) and response errors (failures after the server responds).

You can check whether an unknown value is an HttpClientError using the isHttpClientError guard:

1
import { HttpClientError } from "effect/unstable/http";
2

3
HttpClientError.isHttpClientError(someValue); // true or false

Request Errors

Request errors occur before the server sends a response. The request either couldn’t be built or couldn’t be sent.

TransportError: A network-level failure. The connection timed out, DNS resolution failed, the server refused the connection, or the network is unreachable.
EncodeError: The request body couldn’t be serialized. This typically happens if bodyJson encounters data that JSON.stringify can’t handle.
InvalidUrlError: The URL couldn’t be parsed into a valid URL object.

Every request error includes the original request object, so you always know which request failed.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
} from "effect/unstable/http";
6
import { Effect } from "effect";
7

8
const program = Effect.gen(function* () {
9
  const client = yield* HttpClient.HttpClient;
10

11
  // This will fail with a TransportError (invalid host)
12
  const request = HttpClientRequest.get("https://this-does-not-exist.invalid");
13
  const response = yield* client.execute(request);
14

15
  return yield* response.json;
16
}).pipe(
17
  Effect.catch((error) => {
18
    console.log("Tag:", error._tag);
19
    console.log("Reason:", error.reason._tag);
20
    console.log("Request:", error.reason.methodAndUrl);
21
    console.log("Message:", error.reason.message);
22
    return Effect.void;
23
  }),
24
  Effect.provide(FetchHttpClient.layer),
25
);
26

27
// Test it
28
Effect.runPromise(program);

Output:

1
Tag: HttpClientError
2
Reason: TransportError
3
Request: GET https://this-does-not-exist.invalid
4
Message: Transport error (GET https://this-does-not-exist.invalid)

Notice the structure. The outer error._tag is always "HttpClientError". The error.reason._tag tells you the specific failure type. Properties like methodAndUrl and message live on the reason object.

Response Errors

Response errors occur after the server sends a response but something went wrong when processing it.

It has a reason field with these possible values:

StatusCodeError: The response came back with a status code your code considers unacceptable. For example, a 404 or 500. This error is produced when you explicitly opt in to status code checking using filterStatusOk, filterStatus, or similar filters, which are covered in a later chapter.
DecodeError: The response body couldn’t be parsed. For example, calling response.json on a response that isn’t valid JSON.
EmptyBodyError: You tried to read a body that doesn’t exist (e.g., a 204 No Content response).

Every response error includes both the original request and the response, giving you full context.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
} from "effect/unstable/http";
6
import { Effect } from "effect";
7

8
const program = Effect.gen(function* () {
9
  const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
10

11
  // This returns a 404, which filterStatusOk turns into a StatusCodeError
12
  const request = HttpClientRequest.get("https://dummyjson.com/users/9999");
13
  const response = yield* client.execute(request);
14

15
  return yield* response.json;
16
}).pipe(
17
  Effect.catch((error) => {
18
    console.log("Tag:", error._tag);
19
    console.log("Reason:", error.reason._tag);
20
    if (error.response) {
21
      console.log("Status:", error.response.status);
22
    }
23
    console.log("Request:", error.reason.methodAndUrl);
24
    console.log("Message:", error.reason.message);
25
    return Effect.void;
26
  }),
27
  Effect.provide(FetchHttpClient.layer),
28
);
29

30
// Test it
31
Effect.runPromise(program);

Output:

1
Tag: HttpClientError
2
Reason: StatusCodeError
3
Status: 404
4
Request: GET https://dummyjson.com/users/9999
5
Message: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999)

SchemaError

SchemaError comes from Effect’s Schema module, not from HttpClient itself. You’ll encounter it when using schema-based validation like HttpClientResponse.schemaBodyJson() or HttpClientResponse.schemaHeaders().

When the response body or headers don’t match your schema, the validation step fails with a SchemaError. This error is separate from HttpClientError. It’s a schema validation failure, not an HTTP failure.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
  HttpClientResponse,
6
} from "effect/unstable/http";
7
import { Effect, Schema } from "effect";
8

9
// A schema that expects fields the API doesn't return
10
const WrongSchema = Schema.Struct({
11
  nonExistentField: Schema.String,
12
});
13

14
const program = Effect.gen(function* () {
15
  const client = yield* HttpClient.HttpClient;
16

17
  const request = HttpClientRequest.get("https://dummyjson.com/users/1");
18

19
  const response = yield* client.execute(request);
20

21
  // This will fail because the response doesn't match our schema
22
  const data = yield* HttpClientResponse.schemaBodyJson(WrongSchema)(response);
23

24
  return data;
25
}).pipe(
26
  Effect.catch((error) => {
27
    console.log("Tag:", error._tag);
28
    console.log("Message:", error.message);
29
    return Effect.void;
30
  }),
31
  Effect.provide(FetchHttpClient.layer),
32
);
33

34
// Test it
35
Effect.runPromise(program);

Output:

1
Tag: SchemaError
2
Message: Missing key
3
  at ["nonExistentField"]

HttpClientError

Request Errors

Response Errors

SchemaError

Stay in the loop