The Standard GraphQL Error Shape

The Status Line That Never Complains

A team ships a mobile feed screen. The server answers HTTP 200, the client interceptor sees green, the screen renders blank. Twenty minutes later the logs show a resolver threw on a soft-deleted row. Nothing in the status line mentioned it.

REST habits die hard: check the status, branch on 4xx and 5xx, done. That reflex is wrong for GraphQL. The HTTP layer only carries the request to the server and the bytes back; the outcome of the operation lives entirely in a body whose shape the specification fixes:

{
  "data": {
    "feed": [
      { "id": "p1", "title": "Retry budgets", "author": { "name": "Sam" } },
      { "id": "p2", "title": "Rollback drills", "author": null }
    ]
  },
  "errors": [
    {
      "message": "Cannot return null for non-nullable field Author.name.",
      "locations": [{ "line": 4, "column": 17 }],
      "path": ["feed", 1, "author", "name"]
    }
  ]
}

Three rules follow from the response format:

• data present and non-null: execution ran at least partially. errors may accompany it and names the fields that failed.
• data absent: execution never started. The document failed to parse, failed validation, or its variables could not be coerced, so the response carries only errors.
• data present and null: execution started and a failure propagated all the way to the root of the response. errors must be present.

HTTP has no status code for "half of your request worked", so a fully executed operation returns 200 even when resolvers threw. Servers do disagree about the earlier phases: Apollo Server answers 400 when a document cannot be parsed or validated, while many older stacks return 200 for the same failure because they still use the legacy application/json media type.

The client rule that survives every server: treat the status line as transport health and the body as the operation's result.

Two failure shapes, two different UI responses. A missing data key is a bug in the query or the caller; a populated data with errors is a runtime degradation that partial rendering can absorb.

Which Phase Rejected You: Parse, Validate, or Execute

An entry in errors is not a category. Where it was produced decides which fields it carries and who has to fix it: the developer who wrote the query, or the runtime that must keep rendering.

Parse errors come from the tokenizer — the document has a syntax error. They carry locations pointing into the query text, never path, and no data key, because execution was never scheduled. The fix belongs to whatever produced the string: a broken code generator or a hand-edited operation.

{
  "errors": [
    {
      "message": "Syntax Error: Expected Name, found \"}\"",
      "locations": [{ "line": 3, "column": 12 }]
    }
  ]
}

Validation errors run after parsing and before execution: an unknown field, a missing required argument, a fragment spread on a leaf type. These also point at positions in the document and also have no path — nothing executed, so there is no response position to name.

Coercion errors abort before execution too: the supplied variables do not satisfy their declared types. No path again, and the extensions usually carry per-variable detail so a form can attach the message to the right input.

Field errors are the only ones born during execution: a resolver threw, or returned null for a non-null field. These are the entries with path, and they are the ones allowed to sit next to partial data.

path walks the response, not the schema. ["feed", 1, "author", "name"] reads: field feed, list index 1, field author, field name. Field names are strings, list indices are numbers, and that is exactly the key a logger needs (feed.1.author.name) to group failures by the UI element that broke.

A single response can carry several entries — each failed field contributes its own — and their order follows execution order, not importance. Servers do not deduplicate repeated failures of the same path, so client-side aggregation is worth doing before hitting the error tracker.

Working With Partial Data in the Client

The two response shapes demand different reactions, and most client bugs come from treating them alike.

No data key: the operation never ran. Retrying the identical request reproduces the identical failure, so retry loops waste time. Show a global error, log the message, and stop.

Partial data: the rest of the response is real. Throw it away and you convert a cosmetic hole into a blank screen:

type GqlResult<T> = {
  data?: T | null;
  errors?: { message: string; path?: (string | number)[] }[];
};

function renderFeed(res: GqlResult<{ feed: Post[] }>) {
  // data missing => the request never executed; there is nothing to render
  if (res.data == null) return showGlobalError(res.errors?.[0]?.message);

  const failedPaths = (res.errors ?? [])
    .filter((e) => e.path)                     // only field errors have a path
    .map((e) => e.path!.join('.'));            // "feed.1.author.name"

  for (const post of res.data.feed) {
    render(post, post.author ? post.author.name : 'Author unavailable');
  }
  logFieldFailures(failedPaths);               // grouped in the error tracker
}

Framework defaults often fight this. Apollo Client's errorPolicy: 'none' — the default — treats any GraphQL error as fatal and discards the data in the response; you must opt into errorPolicy: 'all' to receive data and errors together. Reading the raw response from a custom fetcher hides that trap, which is one reason teams standardize on one client.

Retry policy follows the same split:

• Field errors on idempotent reads: retry with backoff if the cause looks transient (a timeout, a rate limit).
• Validation and coercion errors: never retry; they are deterministic.
• Field errors on mutations: never retry automatically. The first attempt may have committed; re-run it only when the operation is declared idempotent.

Interviewers like the debugging version of this topic. The strong answer walks the chain: status line is 200, so read the body; data is null, so a non-null field failed; errors[0].path names it; the path tells you which resolver to open; the resolver shows the null the schema promised could not happen. That is the standard error shape doing its job — it converts "the app is broken" into a file to open.