GraphQL error handling — distinguish operational errors from unexpected errors

GraphQL returns a 200 OK even when errors occur. Unexpected internal errors may leak stack traces or sensitive information. Client code has no structured way to differentiate validation errors from auth errors from server bugs.

Use GraphQLError with typed extensions.code for user-facing errors. Never expose internal errors directly.

import { GraphQLError } from 'graphql';

// Operational error — safe to surface to client
throw new GraphQLError('Email already in use', {
  extensions: { code: 'EMAIL_TAKEN', field: 'email' },
});

// In Apollo Server — mask unexpected errors
const server = new ApolloServer({
  formatError: (formattedError, error) => {
    if (error instanceof GraphQLError && error.extensions.code) {
      return formattedError; // known operational error
    }
    // Unexpected — log internally, return generic message
    console.error(error);
    return { message: 'Internal server error', extensions: { code: 'INTERNAL_ERROR' } };
  },
});

The errors array in a GraphQL response is always present for partial failures. Structured error codes let clients branch on specific conditions. Masking unexpected errors prevents leaking implementation details.

Any production GraphQL server returning errors to clients