ApolloServerPluginErrorHandler severity mapping transition in Apollo Server 4.0

Severity Criteria

Treat GraphQL errors whose extensions.code starts with GRAPHQL_VALIDATION or GRAPHQL_PARSE as 'info' because they are client-fixable. Treat resolver exceptions and any error with INTERNAL_SERVER_ERROR or no code as 'error' so server bugs are not masked.

Request Context Access

Yes. The context object in didEncounterErrors is the same object returned by your server's context function. Attach user or auth there during context construction and read context.user?.role to adjust severity per request. Avoid reading request.headers directly in the plugin for integration portability.

Safe External Alert Routing

Never await Sentry or another transport inside the plugin hook. Push a sanitized payload to a bounded non-blocking queue, flush it on an interval, wrap each send in try/catch, and log locally on failure. Use Sentry.flush(timeout) in a process.on('beforeExit') handler rather than awaiting per request.

Implementation Pattern

Custom Plugin

import { ApolloServerPlugin } from '@apollo/server';

export const severityPlugin: ApolloServerPlugin = {
  async requestDidStart() {
    return {
      async didEncounterErrors({ errors, context }) {
        for (const err of errors) {
          const code = err.extensions?.code ?? '';
          const isClientError =
            code.startsWith('GRAPHQL_VALIDATION') ||
            code.startsWith('GRAPHQL_PARSE');
          err.extensions = {
            ...err.extensions,
            severity: isClientError ? 'info' : 'error',
          };
          if (context.user?.role === 'admin' && isClientError) {
            err.extensions.severity = 'warning';
          }
        }
      },
    };
  },
};

Non-Blocking Sentry Queue

import * as Sentry from '@sentry/node';

const queue: Array<{ error: Error; level: string }> = [];

setInterval(() => {
  const batch = queue.splice(0, 100);
  for (const item of batch) {
    try {
      Sentry.captureException(item.error, { level: item.level as Sentry.SeverityLevel });
    } catch {
      console.error('Sentry send failed', item.error);
    }
  }
}, 1000);

process.on('beforeExit', () => Sentry.flush(2000));

Preserve Spec-Compliant Responses

async willSendResponse({ response }) {
  if (response.errors) {
    const hasCritical = response.errors.some(
      (e) => e.extensions?.severity === 'error'
    );
    if (!hasCritical) {
      response.http.status = 200;
    }
  }
}

Verification

1. Log errors.map((e) => e.extensions?.code) in didEncounterErrors and compare a malformed query against a resolver-thrown error.
2. Log Object.keys(context) inside didEncounterErrors to confirm user or request is present for your integration.
3. Throw in a resolver, confirm the Sentry event carries the correct severity tag, then block the DSN and verify the GraphQL response still returns.

One missing diagnostic detail can change the recommendation: which HTTP integration are you using (Express, Fastify, Lambda, standalone)? The shape of context.request differs by integration, and some middleware may short-circuit before didEncounterErrors runs.