Error handling with async/await in TypeScript

For try/catch, sequential await, and promise rejection behavior in JavaScript, see Async/await in JavaScript and Error handling in JavaScript.

TypeScript does not change runtime errors; it helps you model outcomes so callers handle failures explicitly.

Unknown errors in catch

With useUnknownInCatchVariables (recommended in strict setups), catch (e) types e as unknown. Narrow before use:

1
function isError(value: unknown): value is Error {
2
  return value instanceof Error;
3
}
4

5
async function run() {
6
  try {
7
    await mightFail();
8
  } catch (e: unknown) {
9
    if (isError(e)) {
10
      console.log(e.message);
11
    } else {
12
      console.log(String(e));
13
    }
14
  }
15
}

Per-step errors without nested try/catch

When one catch cannot tell which await failed, split steps or use a typed wrapper that never throws:

1
type Outcome<T> = { ok: true; value: T } | { ok: false; error: unknown };
2

3
async function toOutcome<T>(p: Promise<T>): Promise<Outcome<T>> {
4
  try {
5
    return { ok: true, value: await p };
6
  } catch (error) {
7
    return { ok: false, error };
8
  }
9
}
10

11
async function runAll() {
12
  const a = await toOutcome(fetchUser());
13
  if (!a.ok) return console.log("user failed", a.error);
14

15
  const b = await toOutcome(fetchPosts(a.value.id));
16
  if (!b.ok) return console.log("posts failed", b.error);
17

18
  console.log(b.value);
19
}

After if (!a.ok), TypeScript narrows a.value in the success branch.

Tuple pattern from Promise.allSettled-style helpers

A small handle helper returns a tuple [result, error] with a discriminant empty slot:

1
async function handle<T>(
2
  prom: Promise<T>,
3
): Promise<[T, undefined] | [undefined, unknown]> {
4
  try {
5
    const res = await prom;
6
    return [res, undefined];
7
  } catch (err) {
8
    return [undefined, err];
9
  }
10
}
11

12
async function runAll() {
13
  const [user, errUser] = await handle(fetchUser());
14
  if (errUser !== undefined) {
15
    return console.log("user", errUser);
16
  }
17

18
  const [posts, errPosts] = await handle(fetchPosts(user.id));
19
  if (errPosts !== undefined) {
20
    return console.log("posts", errPosts);
21
  }
22

23
  console.log(posts);
24
}

Annotate generic T on handle when inference from the argument is insufficient.

Typing functions that may throw versus Result types

APIs can be declared to return Promise<T> (throw on failure) or Promise<Outcome<T>> / Result<T, E> (never throw). Pick one style per layer; mixing thrown errors and result objects in the same module confuses both readers and the type checker.

Declare Promise<T> when failures are exceptional. Use Outcome or a shared Result alias when failure is an ordinary branch and you want exhaustiveness checking at call sites.