🎯 The Await Keyword and Error Handling

What Await Really Does

The await operator does one job: it pauses the async function until the Promise beside it settles, then evaluates to that Promise's result. If the Promise fulfils, await gives you the value. If it rejects, await throws the rejection reason at that exact line — which is why try/catch works.

💡 Mental model: think of await as "un-wrap this Promise, or throw if it failed." The rest of your function simply waits its turn.

What Can Be Awaited?

You can await any Promise — but also any thenable (an object with a .then() method) and even plain values. Awaiting a non-Promise simply wraps it in Promise.resolve() first, so it always yields on the next microtask.

// Awaiting a native Promise
const response = await fetch('/api/data');

// Awaiting a Promise you built by hand (a 1-second delay)
await new Promise((resolve) => setTimeout(resolve, 1000));

// Awaiting a thenable — not a real Promise, but compatible
const thenable = { then: (resolve) => resolve('from a thenable') };
const a = await thenable;      // 'from a thenable'

// Awaiting a plain value — wrapped in Promise.resolve automatically
const b = await 42;            // 42 (yields once, then continues)

Await and the Event Loop

When execution hits an await on a pending Promise, the function suspends and returns control to the event loop, which is free to run other code. When the Promise settles, resuming the function is scheduled as a microtask. Microtasks always drain before the next timer callback (a macrotask), which produces some surprising-but-correct ordering.

async function order() {
  console.log('1. start');

  setTimeout(() => console.log('4. timer (macrotask)'), 0);

  await Promise.resolve();        // suspends, schedules a microtask
  console.log('3. after await (microtask)');
}

console.log('0. before call');
order();
console.log('2. after call (sync continues)');

// Console order:
// 0. before call
// 1. start
// 2. after call (sync continues)
// 3. after await (microtask)
// 4. timer (macrotask)

Error Handling with try/catch

Because a rejected await throws, you handle asynchronous errors with the same try/catch you use for synchronous code. A single catch covers every await inside the try block.

async function fetchAndProcess(url) {
  try {
    const response = await fetch(url);

    // fetch only rejects on network failure — check status yourself
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }

    const data = await response.json();
    return process(data);
  } catch (error) {
    console.error('Request failed:', error);
    throw error; // re-throw so the caller can decide what to do
  }
}

Cleanup with finally

A finally block runs after try/catch no matter what — success, handled error, or re-thrown error. It's the right home for releasing resources: closing files, hiding spinners, ending database sessions.

async function loadWithSpinner(url) {
  showSpinner();
  try {
    const res = await fetch(url);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (error) {
    console.error('Load failed:', error);
    throw error;
  } finally {
    // Runs on success AND on failure — the spinner always hides.
    hideSpinner();
  }
}

Custom Error Classes

A single generic Error tells the caller little. By subclassing Error you attach structured data (status codes, field errors) and let callers branch with instanceof.

class ApiError extends Error {
  constructor(message, status, endpoint) {
    super(message);
    this.name = 'ApiError';
    this.status = status;
    this.endpoint = endpoint;
  }
  get isClientError() { return this.status >= 400 && this.status < 500; }
  get isServerError() { return this.status >= 500; }
}

async function fetchUser(userId) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new ApiError(`Could not load user ${userId}`, response.status, `/api/users/${userId}`);
  }
  return response.json();
}

// The caller can now react precisely to the failure type
try {
  const user = await fetchUser('123');
} catch (error) {
  if (error instanceof ApiError && error.isServerError) {
    await reportOutage(error);       // 5xx — alert the team
  } else if (error instanceof ApiError && error.isClientError) {
    showMessage('User not found');   // 4xx — tell the user
  } else {
    throw error;                     // something unexpected
  }
}

The Retry Pattern

Networks fail transiently. A retry with exponential backoff gives a flaky call a few more chances, waiting longer between each attempt (plus a little random "jitter" so many clients don't all retry in lockstep).

async function fetchWithRetry(url, { maxRetries = 3 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      const response = await fetch(url);
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return await response.json();
    } catch (error) {
      if (attempt > maxRetries) {
        console.error(`Giving up after ${maxRetries} retries`);
        throw error;
      }
      // 2^attempt seconds, capped at 10s, plus up to 1s of jitter
      const delay = Math.min(1000 * 2 ** attempt, 10000) + Math.random() * 1000;
      console.warn(`Attempt ${attempt} failed; retrying in ${Math.round(delay)}ms`);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Hands-on Exercise

class HttpError extends Error {
  constructor(status, url) {
    super(`HTTP ${status} for ${url}`);
    this.name = 'HttpError';
    this.status = status;
  }
}

async function fetchJSON(url, { maxRetries = 2 } = {}) {
  for (let attempt = 0; ; attempt++) {
    try {
      const response = await fetch(url);
      if (!response.ok) throw new HttpError(response.status, url);
      return await response.json();
    } catch (error) {
      const isServer = error instanceof HttpError && error.status >= 500;
      const isNetwork = !(error instanceof HttpError);
      const retryable = isServer || isNetwork;

      if (!retryable || attempt >= maxRetries) throw error;

      const delay = 300 * 2 ** attempt + Math.random() * 200;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Summary & Quiz

📚 Further Reading

• MDN — await
• MDN — The event loop
• Jake Archibald — await vs return vs return await

🚀 What's Next?

You can now await confidently and recover from failures. Next we assemble these building blocks into reusable async/await patterns — waterfalls, parallel fan-out, batching, and circuit breakers — that show up in production code every day.