Structured Error Codes with Extensions

Clients Cannot Branch on Prose

A checkout screen needs two different reactions: "session expired" must send the user to login, "email already registered" must attach a message to the email field and keep the form open. The only thing the wire gives you by default is message — a sentence a human wrote.

So someone writes if (err.message.includes('already registered')). It works until a copy review rewords the sentence, until localization ships a translated string, until a server upgrade changes capitalization. Client logic that parses prose is a production incident waiting for a wording change.

The specification anticipated this. Alongside message, locations, and path, an errors entry may carry an extensions map. The spec fixes only its type (a map) and leaves the contents to the server, and it tells clients to tolerate keys they do not recognize. That makes extensions the sanctioned place to grow the error contract without forking the response shape:

{
  "data": null,
  "errors": [
    {
      "message": "Email already registered.",
      "path": ["signup"],
      "extensions": {
        "code": "BAD_USER_INPUT",
        "field": "email",
        "requestId": "01J9F2K7QW8N3M6P4R5T",
        "retryable": false
      }
    }
  ]
}

The client now branches on data, not grammar:

switch (err.extensions?.code) {
  case 'UNAUTHENTICATED':  return redirectToLogin();
  case 'BAD_USER_INPUT':   return attachToField(err.extensions.field, err.message);
  case 'RATE_LIMITED':     return scheduleRetry(err.extensions.retryAfter ?? 30);
  default:                 return reportToTracker(err);
}

The division of labor this sets up matters as much as the field itself: message is for humans reading a toast or a log, extensions.code is for machines making a decision, and everything else in extensions is metadata for correlation and debugging. Servers that put the decision logic only in the sentence force every client to reimplement parsing; servers that put codes in place let the message be reworded freely.

Building the Error Catalog

The tempting design is one code per exception class: UserRepositoryNotFoundError, StripeTimeoutError, CacheDeserializationError. That leaks your class hierarchy to clients and multiplies codes nobody branches on. The useful design keys codes on the decision the client makes, which usually collapses dozens of exceptions into a handful of codes.

Rules that keep a catalog stable across releases:

1. Codes are API surface. Renaming BAD_USER_INPUT breaks clients exactly like renaming a field. Deprecate codes; do not silently swap them.
2. Few codes, forced by decisions. If two codes always trigger the same client branch, merge them.
3. One casing convention, applied everywhere. SCREAMING_SNAKE matches the vocabulary servers already ship, so shared codes and custom codes look like one system.
4. Document each code with its client action, not its server origin.

In graphql-js the code travels with the error object — since v16, the options bag is the place to put it:

import { GraphQLError } from 'graphql';

export const Codes = {
  UNAUTHENTICATED: 'UNAUTHENTICATED',
  BAD_USER_INPUT: 'BAD_USER_INPUT',
} as const;

throw new GraphQLError('Email already registered.', {
  extensions: {
    code: Codes.BAD_USER_INPUT,
    field: 'email',
    requestId: ctx.requestId,   // same value the access log records
  },
});

// Client-side union derived from the same constants file:
type KnownCode = (typeof Codes)[keyof typeof Codes];

Note what the server does when you do not set a code: an unexpected throw surfaces as INTERNAL_SERVER_ERROR with the original message hidden. The catalog therefore works in both directions — codes you set deliberately reach clients, and anything unplanned lands in the generic bucket instead of leaking its shape.

Keep extensions small. Every entry is serialized once per error, and a response can carry dozens; a result-set payload attached "for debugging" multiplies quickly.

Correlate, Mask, and Map to Status Codes

A support ticket says "the app said something went wrong." The useful reply names a log line. That link is an extensions field: mint an identifier when the error is formatted, log it with the full context, and return it with the sanitized message.

// Server: formatter runs once per error before it hits the wire
function toWire(err: GraphQLError, ctx: Ctx) {
  const internal = !(err.extensions?.code);      // anything without a catalog code
  const errorId = randomUUID();

  logger.error({
    errorId,                                      // <- what support quotes back to us
    code: err.extensions?.code ?? 'INTERNAL_SERVER_ERROR',
    path: err.path,
    stack: err.originalError?.stack,              // full detail stays server-side
    requestId: ctx.requestId,
  });

  if (!internal) return err;                      // catalog errors pass through
  return new GraphQLError('Something went wrong on our side.', {
    extensions: { code: 'INTERNAL_SERVER_ERROR', errorId, requestId: ctx.requestId },
  });
}

Masking is an allowlist, not a blacklist. Do not try to scrub SQL keywords out of arbitrary messages; default to replacing anything outside the catalog with a fixed sentence plus an errorId. Stack traces are the extreme case: Apollo Server exposes includeStacktraceInErrorResponses, and production deployments keep it off so extensions never carries server internals. File paths, driver messages, and upstream URLs are all in the same category.

HTTP status codes are the wrong tool for per-field failures. Once execution began, the response is a normal GraphQL result and the guidance is to keep it at 200 — see the standard error shape for why. Where status codes still help is at the request level: authentication rejected in context (401/403), throttling (429), or a caller that failed basic request validation (400). Apollo lets you express that without leaving GraphQL semantics:

throw new GraphQLError('Slow down.', {
  extensions: { code: 'RATE_LIMITED', retryAfter: 30, http: { status: 429 } },
});

Use extensions.http sparingly — clients that branch on status codes instead of extensions.code are the pattern this topic exists to replace.

Finally, treat codes as a versioned surface: count how often each code fires, announce changes to the catalog the way you announce schema changes, and tell clients to fall back to generic handling for codes they do not know. An unknown extensions key is legal; an unknown code the client maps to a specific screen is a support ticket.

Interview framing: when asked how a client tells "log in again" from "fix your input", answer with the mechanism (a stable code inside extensions), the policy (codes keyed to client decisions, frozen once shipped), and the safety story (allowlist masking, errorId correlation, status codes reserved for request-level failures).