Catching Multiple Error Types | Effect Http Client

HttpClient.catchTags() handles multiple error types in a single call, with a separate handler for each _tag.

This is the cleanest option when your client’s error channel contains several error types and you want distinct recovery strategies for each.

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

9
const User = Schema.Struct({
10
  id: Schema.Number,
11
  firstName: Schema.String,
12
  lastName: Schema.String,
13
});
14

15
function fetchUser(userId: number) {
16
  return Effect.gen(function* () {
17
    const client = (yield* HttpClient.HttpClient).pipe(
18
      HttpClient.filterStatusOk,
19
      HttpClient.catchTags({
20
        HttpClientError: (error) =>
21
          Effect.gen(function* () {
22
            console.log(`HTTP error: ${error.message}`);
23
            console.log("Falling back to default user...");
24
            const fallbackClient = yield* HttpClient.HttpClient;
25
            return yield* fallbackClient.get("https://dummyjson.com/users/1");
26
          }),
27
      }),
28
    );
29

30
    const request = HttpClientRequest.get(
31
      `https://dummyjson.com/users/${userId}`,
32
    );
33

34
    const response = yield* client.execute(request);
35
    const user = yield* HttpClientResponse.schemaBodyJson(User)(response);
36

37
    return user;
38
  }).pipe(Effect.provide(FetchHttpClient.layer));
39
}
40

41
// Test with an invalid user — HttpClientError is caught, fallback is used
42
Effect.runPromise(fetchUser(9999)).then(
43
  (user) => console.log("User:", user.firstName, user.lastName),
44
  (error) => console.error(`[${error._tag}] ${error.message}`),
45
);

Output:

1
HTTP error: StatusCode: non 2xx status code (404 GET https://dummyjson.com/users/9999)
2
Falling back to default user...
3
User: Emily Johnson

catchTags takes an object where each key is a _tag value and each value is a handler function. You don’t need to handle every possible tag, only the ones you list. Unhandled tags remain in the error channel.

In this example, HttpClientError is caught and recovered with a fallback request. But SchemaError (from schemaBodyJson) is not listed, so it would propagate to the caller if the response shape doesn’t match the schema.

catchTags shines when you have three or more error types in the channel and want to handle each one differently in a single, readable block. If you only need to catch one specific tag, catchTag is simpler. If you want to catch everything, use catch.

Stay in the loop