How should GraphQL request metrics count errors returned in a successful response?

## Why the usual error metric reads zero Every generic HTTP monitor computes error rate the same way: count responses whose status indicates failure, divide by total. On a GraphQL endpoint that computation can sit at zero through an outage, because GraphQL's failure channel is the response *body*. The execution result is a map with up to three entries — `data`, `errors` and `extensions` — and a response that carries a fully populated `errors` list is still, from the transport's point of view, a response that was produced successfully. Exactly which status accompanies which outcome is the transport layer's concern and varies with the media type in play; for metrics the rule is simpler and does not depend on it. **Parse the body.** ## The two failure classes, and why they are not one counter The envelope distinguishes them structurally, so your metric can too. **Request errors** happen before execution begins: the document does not parse, it fails a validation rule, the requested operation is not in the document, a required variable is absent or of the wrong type. The response contains `errors` and — this is the checkable signal — **no `data` entry at all**. The caller received nothing usable. Nothing your resolvers do is implicated; the document itself was rejected. **Field errors** happen during execution: a resolver raised, or returned something the field's type could not accept. Execution continues, the failed position is set to null (propagating up to the nearest nullable parent), and an entry is appended to `errors` describing what failed and, for field errors, a `path` locating the position in the response. `data` is present. The caller usually received most of what it asked for. One is "we could not run your request". The other is "we ran it and part of it broke". Rolling them into one `graphql.errors` counter destroys the only distinction that changes what you do next, and it makes the counter unreadable: a spike could mean a client shipped an invalid document or a downstream benefits provider is down, and the number cannot tell you which. ## Count requests, not entries The `errors` list is a list. A reconciliation document that touches an 8,400-row page of payslips can fail in thousands of positions from one downstream outage, and a counter incremented once per entry will report thousands of "errors" for a handful of requests. That metric has no denominator you can reason about: the ratio of error entries to requests is not a rate of anything. Count at the request grain. For each executed request, emit exactly one increment into exactly one outcome bucket: * `request_error` — no `data` entry; execution never began. * `field_error` — `data` present and `errors` non-empty; partial result. * `ok` — `data` present and no `errors` entry. Now error rate is a fraction of requests, it sums to one, and it can be dimensioned by the same operation identity and operation type as your duration metric. If you also want a sense of blast radius inside a request, record the count of error entries as a *separate* distribution — but never as the numerator of a rate. ## A worked incident: a client pinned to a removed field A payroll and benefits schema drops `BenefitEnrollment.employerContributionCents` in a release. A mobile build from eleven weeks ago still ships a document selecting it. From the moment the new schema is live, every request from that build fails **validation** — the field does not exist on the type — so the response has `errors` and no `data`, and the app shows an empty benefits screen. What the dashboards show depends entirely on what they meter. A transport-outcome error rate may show nothing at all. A single lumped `errors` counter shows a rise with no explanation. The split counters show it precisely: `request_error` climbs while `field_error` and `ok` are steady, which says the shape of what clients are sending changed, not that a backend broke — and dimensioned by operation, it names the operation. That is a one-minute diagnosis instead of an afternoon. ## Two wrinkles worth naming **Do not dimension by error message.** Messages are free text, frequently interpolate identifiers, and are therefore unbounded as a label. Servers commonly place a stable classification code under an error entry's `extensions` — that is a widespread convention, not something the specification defines — and if yours does, that code is the safe dimension. If it does not, dimension by the failure class you can determine structurally. **Errors-as-data undercounts you.** A schema that models expected failures as result types — a union of a success payload and a typed failure payload — produces no `errors` entry at all when the failure occurs. Those requests land in your `ok` bucket, correctly, because execution succeeded. If a meaningful share of real failures is modelled that way, this metric alone will not see them and you need domain counters emitted where those payloads are constructed.