Error Object Shape

## What this is about A GraphQL response is a map. When something went wrong, that map carries an `errors` entry holding a **list**, and each item in that list is itself a small map describing one failure. The response envelope — which top-level keys exist, when `data` is absent — is a separate concern. This is about the shape of **one item inside the list**, and its vocabulary is deliberately tiny: `message`, `locations`, `path`, `extensions`. ## message — the one entry that is always required Every error **must** carry `message`, a string describing the failure. The specification says nothing about its structure, its language, or its wording. It is prose written for a human being who is debugging, and that is the whole of its contract. The consequence matters more than the rule: because nothing constrains the text, nothing stops it changing. A server upgrade rewords it, a translation layer localises it, a hardening pass replaces it wholesale with something bland. Any program that branches on it is depending on an unversioned string. Log it, show it to a developer, put it in a bug report — never write `if (message.includes(...))`. ## locations — where in the document the caller wrote it Optional. When the error can be tied to a point in the document that was sent, the error **should** carry `locations`: a list of maps, each holding `line` and `column`, both **positive integers starting at 1**, marking the beginning of the associated syntax element. It is a list because a single error can implicate more than one place in the document. Note what it points at: the **text the client sent**, not the schema file and not the response. It answers "where did you write this?", never "where in the data did it break?". ## path — where in the response the failure landed When an error can be associated with a particular field of the result, the error **must** carry `path`. It is a list of segments running from the root of `data` down to that field. Segments that name fields are strings — the **response keys**, so an aliased field appears under its alias — and segments that name a position inside a list field are **0-indexed integers**. The asymmetry is a favourite interview trap: `locations` counts lines and columns from **1**; `path` counts list positions from **0**. They are different coordinate systems over different artefacts, and there is no reason for them to agree. `path` is what makes a partial response usable at all. Without it, a caller holding a body full of `null`s cannot tell a value that is legitimately absent from a hole left by a failure. ## extensions — the one sanctioned free slot A service **may** add an `extensions` entry. If present its value must be a map, and the specification then imposes nothing whatsoever on its contents. This is the designated home for everything the format does not model: a machine-readable code, a correlation id, a timestamp, a retry hint, timing data. Two things candidates routinely get wrong here. First, the `code` key inside `extensions` is a **widespread convention among server implementations, not a specified key** — the spec knows about `extensions` and nothing about what goes in it. Second, the per-error `extensions` map is not the response's own top-level `extensions` entry; they are different maps at different levels, and a client reading the wrong one finds nothing. ## Why you may not invent a fifth top-level entry The specification tells services **not** to add other entries directly to an error map, because that namespace is reserved for future editions of the specification to grow into. So a bespoke `severity` sitting beside `message` is out of contract; `extensions.severity` is entirely fine. That single rule is why `extensions` exists at all. ## Worked example A warehouse inventory graph. `StockItem` is one of those types that accreted for years — 37 fields, one of which, `reorderPoint`, is computed by a forecasting service that has just timed out for the item in list position 11: ```json { "data": { "warehouse": { "bins": [ { "stockItems": [ null ] } ] } }, "errors": [ { "message": "Forecast service timed out", "locations": [ { "line": 6, "column": 11 } ], "path": [ "warehouse", "bins", 4, "stockItems", 11, "reorderPoint" ], "extensions": { "code": "UPSTREAM_TIMEOUT", "traceId": "8f21c4" } } ] } ``` Read it entry by entry. `message` tells the on-call engineer what happened. `locations` says the offending field was written on line 6, column 11 of the document that was sent. `path` says the failure belongs to `reorderPoint` of the twelfth stock item (index 11) inside the fifth bin (index 4). `extensions.code` is the only part of the whole error a client should branch on, and it is there because this server chose to put it there. ## Why one error map, and why a list GraphQL is transport-independent, so an error cannot be an HTTP status; the response has to describe the failure itself. And execution does not stop at the first bad field — sibling fields keep resolving — so one response can legitimately carry several errors at once. A list of self-describing maps is the smallest structure that supports both facts.