When working with remote data in React applications, handling errors gracefully is crucial for a smooth user experience. React Query provides several tools to manage errors and retry failed requests, making your application more resilient to network issues or server problems. One important concept is the use of error boundaries. In React, error boundaries are components that catch JavaScript errors anywhere in their child component tree and display a fallback UI. React Query can work seamlessly with React error boundaries, allowing you to show user-friendly error messages when something goes wrong during data fetching.

React Query also offers built-in retry options for queries. By default, if a query fails (for example, due to a network error), React Query will automatically retry the request a few times before considering it a final failure. You can customize this behavior using the retry and retryDelay options in your query configuration. For example, you might want to reduce the number of retries or add a longer delay between attempts if your API is rate-limited. This flexibility lets you balance responsiveness with robustness, ensuring that transient errors don't immediately disrupt your users.

Custom error handling is another key feature. With React Query, you can access the error object in your components and display helpful messages or take specific actions based on the error type. For instance, you might want to ask users to check their internet connection, or offer a Try Again button if a request fails. By combining error boundaries, retry strategies, and custom error messages, you can make your application much more user-friendly and reliable, even when things go wrong behind the scenes.

Suppose you are fetching a list of users from an API and want to handle errors gracefully. You can configure the query to retry failed requests only twice, and display a clear error message if all attempts fail. Here is how you might set this up using React Query:

import { useQuery } from '@tanstack/react-query';

function UsersList() {
  const { data, error, isError, isLoading, refetch } = useQuery({
    queryKey: ['users'],
    queryFn: () =>
      fetch('/api/users').then((res) => {
        if (!res.ok) {
          throw new Error('Network response was not ok');
        }
        return res.json();
      }),
    retry: 2,        // Only retry twice
    retryDelay: 2000 // Wait 2 seconds between retries
  });

  if (isLoading) return <div>Loading...</div>;

  if (isError) {
    return (
      <div>
        <p>Sorry, we could not load users. {error.message}</p>
        <button onClick={() => refetch()}>Try Again</button>
      </div>
    );
  }

  return (
    <ul>
      {data.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

In this example, the query will retry up to two times with a two-second delay between attempts. If all retries fail, a user-friendly error message is shown, along with a button to retry the request manually. This approach helps users understand what went wrong and gives them control to try again, rather than leaving them with a blank or broken page.