Catching Specific Error Types | Effect Http Client

HttpClient.catchTag() catches only errors with a specific _tag, letting other error types pass through.

This is useful when your client’s error channel contains multiple error types. For example, if you use schema validation on responses, the error channel includes both HttpClientError (from the HTTP request) and SchemaError (from validation). catchTag lets you recover from one while letting the other propagate.

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
      // Only catch HttpClientError (network failures, bad status codes, etc.)
20
      // SchemaError from validation is NOT caught — it will still propagate
21
      HttpClient.catchTag("HttpClientError", (error) =>
22
        Effect.gen(function* () {
23
          console.log(`HTTP error: ${error.message}`);
24
          console.log("Falling back to default user...");
25
          const fallbackClient = yield* HttpClient.HttpClient;
26
          return yield* fallbackClient.get("https://dummyjson.com/users/1");
27
        }),
28
      ),
29
    );
30

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

35
    const response = yield* client.execute(request);
36

37
    // This can fail with SchemaError, which is NOT caught by catchTag above
38
    const user = yield* HttpClientResponse.schemaBodyJson(User)(response);
39

40
    return user;
41
  }).pipe(Effect.provide(FetchHttpClient.layer));
42
}
43

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

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

All HTTP client errors share a single type: HttpClientError (with _tag: "HttpClientError"). The specific failure kind — transport error, status code error, decode error, etc. — is in the error.reason._tag field. This means catchTag("HttpClientError", ...) catches all HTTP-related errors.

The power of catchTag shows when other error types are in the channel. In this example, a SchemaError from schemaBodyJson would bypass the catchTag handler entirely and propagate to the caller. This lets you be precise: recover from HTTP failures (server down, bad status code) while still surfacing data integrity issues (unexpected response shape) as errors that need attention.

If your client only produces HttpClientError and you want to catch everything, HttpClient.catch is simpler. Reach for catchTag when multiple error types are in play and you need selective recovery.

Stay in the loop