Async/Await with Fetch API in Node.js

The Problem: Waiting for the Network

Imagine you're at a busy coffee shop. You place your order (a network request), but instead of the barista making you stand at the counter and wait motionlessly, they give you a buzzer. You're now free to find a table, check your phone, or talk to a friend. When your coffee is ready, the buzzer goes off, and you go pick it up.

This is the essence of asynchronous programming. Synchronous (or blocking) code would be like being forced to stare at the barista until your coffee is done, unable to do anything else. JavaScript, especially in Node.js, is built for the "buzzer" model because waiting for network responses, file reads, or database queries can be slow and unpredictable.

To manage this, JavaScript has evolved its tools. Let's start with a short video that introduces the history, from clunky "callbacks" to the modern approach we'll be using.

As the video explains, Promises were a huge step forward. A Promise is an object that represents the eventual completion (or failure) of an asynchronous operation. It's the "buzzer" from our coffee shop analogy. It can be in one of three states:

• Pending: The operation hasn't finished yet (your coffee is being made).
• Fulfilled: The operation completed successfully (your coffee is ready!).
• Rejected: The operation failed (they're out of almond milk).

Introducing fetch: Your Tool for Network Requests

The primary way we'll make network requests is with the fetch API. It's built directly into modern versions of Node.js (including the version 22+ we installed) and it is Promise-based. When you call fetch, it immediately returns a Promise in the pending state.

Let's see this in action. The next segment of the video demonstrates using fetch and handling the resulting Promise with .then(), the traditional method before async/await became popular.

The .then() syntax works, but as you can imagine, chaining multiple steps can still become difficult to read. This is where async/await comes in.

async/await: The Modern, Readable Approach

async/await is a modern feature built on top of Promises that lets you write asynchronous code that looks and behaves like synchronous code. This makes it incredibly intuitive and is the standard for modern JavaScript development.

There are two keywords:

1. async: You place this before a function declaration. It does two things:
   • It ensures the function always returns a Promise.
   • It allows you to use the await keyword inside it.
2. await: You place this before any Promise-based function (like fetch). It "pauses" the execution of your async function until the Promise settles (is fulfilled or rejected) and then returns the result.

This article from javascript.info provides a fantastic, concise explanation with clear code examples.

Let's Code It

Time to get your hands dirty. Let's use async/await to fetch some data from a public API.

1. In your my-first-node-project folder, create a new file called fetch-test.js.

2. Add the following code. We'll use JSONPlaceholder, a free fake API for testing.

   // fetch-test.js
   
   async function getTodo() {
     console.log('Fetching a todo item...');
   
     // The 'try...catch' block is for error handling, which we'll cover next.
     try {
       // 1. Make the network request. 'await' pauses here until we get a response.
       const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');
   
       // 2. 'await' pauses again to parse the response body as JSON.
       const data = await response.json();
   
       // 3. Now we have the data!
       console.log('Todo Item:', data);
   
     } catch (error) {
       console.error('Something went wrong:', error);
     }
   }
   
   // Call the function to run it.
   getTodo();
   

3. Run the file from your terminal:

   node fetch-test.js
   

You should see the script log "Fetching a todo item..." and then, after a brief moment, the data for the first "todo" item from the API. Notice how readable the code inside the try block is!

Essential: Proper Error Handling

A common mistake is to assume a fetch call only fails if the network is down. This is not true! An API can respond with an error status like 404 Not Found or 401 Unauthorized. The fetch Promise will still fulfill in these cases because a response was successfully received from the server.

This is why you must always check the response status. The Response object from fetch has a handy boolean property called response.ok which is true for successful statuses (like 200 OK) and false for error statuses (like 404 or 500).

To handle both network errors and API errors gracefully, we use a try...catch block combined with a check for response.ok.

This article from ScrapingBee has an excellent section on this.

Let's update our fetch-test.js to include this robust error handling.

// fetch-test.js

async function getTodo() {
  console.log('Fetching a todo item...');

  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');

    // This is the crucial check!
    if (!response.ok) {
      // If the response is not ok, throw an error to be caught by the 'catch' block.
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Todo Item:', data);

  } catch (error) {
    // This 'catch' now handles both network failures and bad HTTP statuses.
    console.error('Error fetching data:', error);
  }
}

getTodo();

This pattern—wrapping await fetch(...) in try...catch and checking !response.ok—is the standard you should use for all future API calls.

async function getUser() {
  console.log('Fetching user data...');

  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users/3');

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const userData = await response.json();

    console.log('User found!');
    console.log('Name:', userData.name);
    console.log('Email:', userData.email);

  } catch (error) {
    console.error('Error fetching user:', error);
  }
}

getUser();

Fetching user data...
User found!
Name: Clementine Bauch
Email: Nathan@yesenia.net

Conclusion

Fantastic! You've just mastered one of the most powerful and essential patterns in modern JavaScript. You learned why asynchronous operations are necessary and how to handle them cleanly and safely.

Here are the key takeaways from this lesson:

• Asynchronous operations prevent your application from freezing while waiting for slow tasks like network requests.
• The fetch API is the modern, built-in tool for making HTTP requests in Node.js, and it returns a Promise.
• async/await provides a highly readable, synchronous-looking syntax for working with Promises.
• For robust code, always wrap your await calls in a try...catch block and check the response.ok property to handle both network errors and API errors.

We are now fully equipped to interact with a real AI API. We know how to store our key securely (from the last lesson) and we know how to make a network request (from this lesson).

In our next lesson, we will combine these skills to send our very first prompt to the Claude API using Node.js and log the response. Let's get started