Best Practices for Error Handling in GraphQL with Apollo Server 4

Introduction

Welcome to the lesson on Best Practices for Error Handling in GraphQL . In this lesson, we will explore how to handle errors effectively in your GraphQL API using Apollo Server 4 and TypeScript . Proper error handling is crucial for building reliable and user-friendly applications.

How GraphQL Handles Errors and Common Error Types

In REST API, a single error usually results in the entire request failing with an HTTP error status. However, In GraphQL, partial success is possible because errors are isolated to specific fields. GraphQL treats errors as part of the response format. If any field in a query fails, it includes an errors array in the response. Common error types include: User Input Errors Authentication Errors Validation Errors System Errors

Creating Custom Error Classes

Since Apollo Server 4 removed built-in error classes, we'll create our own error handling system: TypeScriptimport { GraphQLError } from 'graphql'; export class ValidationError extends GraphQLError { constructor(message: string) { super(message, { extensions: { code: 'BAD_USER_INPUT', http: { status: 400 } } }); } } export class NotFoundError extends GraphQLError { constructor(message: string) { super(message, { extensions: { code: 'NOT_FOUND', http: { status: 404 } } }); } } export class AuthenticationError extends GraphQLError { constructor(message: string) { super(message, { extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } } }); } }

Implementing Basic Error Handling in Resolvers

Let's implement error handling using our custom error classes: TypeScriptimport { ApolloServer } from '@apollo/server'; import { startStandaloneServer } from '@apollo/server/standalone'; interface Book { id: string; title: string; author: string; } const books: Book[] = [ { id: '1', title: 'The Hobbit', author: 'J.R.R. Tolkien' }, { id: '2', title: 'Harry Potter', author: 'J.K. Rowling' } ]; const resolvers = { Query: { book: (_: unknown, { id }: { id: string }) => { const book = books.find(book => book.id === id); if (!book) { throw new NotFoundError(`Book with ID ${id} not found`); } return book; }, } };

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Here's how to validate inputs using our custom error handling:

TypeScript

const resolvers = {
  Mutation: {
    addBook: (_: unknown, { title, author }: { title: string; author: string }) => {
      const validationErrors: string[] = [];
      
      if (!title?.trim()) {
        validationErrors.push('Title is required');
      }
      if (!author?.trim()) {
        validationErrors.push('Author is required');
      }
      
      if (validationErrors.length > 0) {
        throw new ValidationError(validationErrors.join(', '));
      }
      
      const newBook = { 
        id: String(books.length + 1), 
        title: title.trim(), 
        author: author.trim() 
      };
      books.push(newBook);
      return newBook;
    },
  }
};

const resolvers = {
  Mutation: {
    addBook: (_: unknown, { title, author }: { title: string; author: string }) => {
      const validationErrors: string[] = [];
      
      if (!title?.trim()) {
        validationErrors.push('Title is required');
      }
      if (!author?.trim()) {
        validationErrors.push('Author is required');
      }
      
      if (validationErrors.length > 0) {
        throw new ValidationError(validationErrors.join(', '));
      }
      
      const newBook = { 
        id: String(books.length + 1), 
        title: title.trim(), 
        author: author.trim() 
      };
      books.push(newBook);
      return newBook;
    },
  }
};

Apollo Server 4 allows you to customize error formatting using the formatError option:

TypeScript

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // Log the error internally
    console.error('GraphQL Error:', error);

    // Don't expose internal server errors to the client
    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return new GraphQLError('Internal server error', {
        extensions: {
          code: 'INTERNAL_SERVER_ERROR',
          http: { status: 500 }
        }
      });
    }

    return formattedError;
  },
});

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // Log the error internally
    console.error('GraphQL Error:', error);

    // Don't expose internal server errors to the client
    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return new GraphQLError('Internal server error', {
        extensions: {
          code: 'INTERNAL_SERVER_ERROR',
          http: { status: 500 }
        }
      });
    }

    return formattedError;
  },
});

Complete Application Example

Here's a complete example putting it all together:

TypeScript

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { GraphQLError } from 'graphql';

// Type definitions
const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    book(id: ID!): Book
  }

  type Mutation {
    addBook(title: String!, author: String!): Book
  }
`;

// Custom error classes
class ValidationError extends GraphQLError {
  constructor(message: string) {
    super(message, {
      extensions: {
        code: 'BAD_USER_INPUT',
        http: { status: 400 }
      }
    });
  }
}

class NotFoundError extends GraphQLError {
  constructor(message: string) {
    super(message, {
      extensions: {
        code: 'NOT_FOUND',
        http: { status: 404 }
      }
    });
  }
}

// Data store
interface Book {
  id: string;
  title: string;
  author: string;
}

const books: Book[] = [
  { id: '1', title: 'The Hobbit', author: 'J.R.R. Tolkien' },
  { id: '2', title: 'Harry Potter', author: 'J.K. Rowling' }
];

// Resolvers
const resolvers = {
  Query: {
    book: (_: unknown, { id }: { id: string }) => {
      const book = books.find(book => book.id === id);
      if (!book) {
        throw new NotFoundError(`Book with ID ${id} not found`);
      }
      return book;
    },
  },
  Mutation: {
    addBook: (_: unknown, { title, author }: { title: string; author: string }) => {
      const validationErrors: string[] = [];
      
      if (!title?.trim()) {
        validationErrors.push('Title is required');
      }
      if (!author?.trim()) {
        validationErrors.push('Author is required');
      }
      
      if (validationErrors.length > 0) {
        throw new ValidationError(validationErrors.join(', '));
      }
      
      const newBook = { 
        id: String(books.length + 1), 
        title: title.trim(), 
        author: author.trim() 
      };
      books.push(newBook);
      return newBook;
    },
  }
};

// Server setup
const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    console.error('GraphQL Error:', error);

    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return new GraphQLError('Internal server error', {
        extensions: {
          code: 'INTERNAL_SERVER_ERROR',
          http: { status: 500 }
        }
      });
    }

    return formattedError;
  },
});

const startServer = async () => {
  const { url } = await startStandaloneServer(server, { 
    listen: { port: 4000 } 
  });
  console.log(`🚀 Server ready at ${url}`);
};

startServer().catch(console.error);

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { GraphQLError } from 'graphql';

// Type definitions
const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    book(id: ID!): Book
  }

  type Mutation {
    addBook(title: String!, author: String!): Book
  }
`;

// Custom error classes
class ValidationError extends GraphQLError {
  constructor(message: string) {
    super(message, {
      extensions: {
        code: 'BAD_USER_INPUT',
        http: { status: 400 }
      }
    });
  }
}

class NotFoundError extends GraphQLError {
  constructor(message: string) {
    super(message, {
      extensions: {
        code: 'NOT_FOUND',
        http: { status: 404 }
      }
    });
  }
}

// Data store
interface Book {
  id: string;
  title: string;
  author: string;
}

const books: Book[] = [
  { id: '1', title: 'The Hobbit', author: 'J.R.R. Tolkien' },
  { id: '2', title: 'Harry Potter', author: 'J.K. Rowling' }
];

// Resolvers
const resolvers = {
  Query: {
    book: (_: unknown, { id }: { id: string }) => {
      const book = books.find(book => book.id === id);
      if (!book) {
        throw new NotFoundError(`Book with ID ${id} not found`);
      }
      return book;
    },
  },
  Mutation: {
    addBook: (_: unknown, { title, author }: { title: string; author: string }) => {
      const validationErrors: string[] = [];
      
      if (!title?.trim()) {
        validationErrors.push('Title is required');
      }
      if (!author?.trim()) {
        validationErrors.push('Author is required');
      }
      
      if (validationErrors.length > 0) {
        throw new ValidationError(validationErrors.join(', '));
      }
      
      const newBook = { 
        id: String(books.length + 1), 
        title: title.trim(), 
        author: author.trim() 
      };
      books.push(newBook);
      return newBook;
    },
  }
};

// Server setup
const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    console.error('GraphQL Error:', error);

    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return new GraphQLError('Internal server error', {
        extensions: {
          code: 'INTERNAL_SERVER_ERROR',
          http: { status: 500 }
        }
      });
    }

    return formattedError;
  },
});

const startServer = async () => {
  const { url } = await startStandaloneServer(server, { 
    listen: { port: 4000 } 
  });
  console.log(`🚀 Server ready at ${url}`);
};

startServer().catch(console.error);

And here's how to make queries to the server:

TypeScript

import fetch from 'node-fetch';

const url = 'http://localhost:4000/';

interface GraphQLResponse<T> {
  data?: T;
  errors?: Array<{
    message: string;
    extensions?: {
      code: string;
    };
  }>;
}

const fetchBook = async (id: string) => {
  const query = `
    query GetBook($id: ID!) {
      book(id: $id) {
        title
        author
      }
    }
  `;
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query,
        variables: { id },
      }),
    });

    const data: GraphQLResponse<{ book: { title: string; author: string } }> = 
      await response.json();

    if (data.errors) {
      console.error('GraphQL Errors:', data.errors);
      return;
    }

    console.log('Book data:', data.data);
  } catch (error) {
    console.error('Network Error:', error);
  }
};

const addNewBook = async (title: string, author: string) => {
  const mutation = `
    mutation AddBook($title: String!, $author: String!) {
      addBook(title: $title, author: $author) {
        id
        title
        author
      }
    }
  `;

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query: mutation,
        variables: { title, author },
      }),
    });

    const data: GraphQLResponse<{ addBook: { id: string; title: string; author: string } }> = 
      await response.json();

    if (data.errors) {
      console.error('GraphQL Errors:', data.errors);
      return;
    }

    console.log('New book added:', data.data);
  } catch (error) {
    console.error('Network Error:', error);
  }
};

// Test the functions
fetchBook('1');
addNewBook('1984', 'George Orwell');

In this updated lesson, you learned:

How to create custom error classes in Apollo Server 4
Best practices for error handling and validation
How to use the formatError function to customize error responses
Type-safe approaches to both server and client-side code
Modern GraphQL patterns including proper variable usage

Remember that good error handling not only improves the developer experience but also helps build more reliable and maintainable applications. Keep practicing these patterns in your GraphQL APIs!

Introduction

How GraphQL Handles Errors and Common Error Types

Creating Custom Error Classes

Implementing Basic Error Handling in Resolvers

Join the 1M+ learners on CodeSignal

Validating User Inputs

Handling Multiple Errors with formatError

Complete Application Example

Queries Example

Lesson Summary