- The GraphQL project published the first GraphQL over HTTP specification, adding a media type and status-code guidance for web servers, clients and proxies. Implementers may choose other fitting codes.
- Many servers reported success even for failed requests, which made service health hard to read. The new guidance lets status codes carry that information.
- Ask which GraphQL services your monitoring reads as healthy only because every reply says 200, and whether your libraries follow the specification.
A service that answers "OK" when something is broken is a quiet kind of problem. Dashboards stay green. Alerts stay silent. With a pattern where every reply says 200, the people who run the system can learn about failure from customers. A new standard from the GraphQL project targets one version of this problem, and the fix is a lesson in how shared conventions become shared contracts.
Why every answer said 200
GraphQL is a way for software to ask a server for exactly the data it needs. Since its 2015 release, the GraphQL specification has said nothing about how requests travel. The project's announcement on graphql.org says you could use it over raw TCP or even "avian carriers".
Most people use it over HTTP, the ordinary web protocol. With no specification for that, the announcement says, interoperability with other HTTP tools and observability were harder than they should have been.
The announcement describes a common workaround. Many servers answered with the standard application/json type. A client then could not tell a genuine GraphQL reply from an error page sent by a proxy or cache. So most implementations returned status code 200 whenever the reply was untampered. The project says this led to jokes about "200 Not OK". As it puts it, "it's hard to get the status of your service if everything is a 200."
What the specification changes
The specification adds a new media type, application/graphql-response+json. A media type is the label that tells software what kind of content it received. When a client sees this label, the announcement says, it can parse the body as a well-formed GraphQL response whatever the status code is.
That removes the reason for the 200 habit. The label now vouches for the reply, so the status code is free to describe what happened. The specification's guidance is simple. If the request returned data, send a 2xx code. If it returned only errors, send a 4xx or 5xx code. It also lists 406 for an unsupported media type requested and 415 for an unsupported media type provided.
The announcement adds a new 294 Partial Success code for replies that hold both data and errors. The project says implementers may pick another code if it fits the situation and stays consistent with the general rule.
The GraphQL specification itself stays transport agnostic. The HTTP document is a supplement. It also carries non-normative notes on security, partial success and future compatibility.
The idea behind it
This is a small change with a larger lesson. A habit that every team adopts on its own looks like a standard until two systems have to cooperate. Then each team's private convention becomes everyone's integration cost.
This resembles how shared conventions work elsewhere on the web, such as HTTP caching headers, where agreed labels let a cache act without knowing what an application does. That is our analogy, not the project's claim. Here, a status code that means something lets a load balancer, a monitor or a cache do its job without special knowledge of GraphQL.
What is still open
The project names three items for later work. First, it plans to support the QUERY HTTP verb, which the IETF just moved to a proposed standard. Second, it wants a standard approach to persisted documents, a long-used technique for storing queries ahead of time. The project says different implementations used it for performance, security or observability. Third, it points to request batching, especially for composite schemas and schemas you do not control.
These are intentions, not features. The announcement says QUERY did not make this first release because the team did not want to rush it.
The authors also say that most GraphQL frameworks and libraries already support the new specification. That is their claim. Your own stack may differ.
What to ask your teams
Ask which GraphQL services your organisation runs or buys, and whether their libraries follow the new specification. Ask whether any dashboard or alert reads a stream of 200 codes as proof of health. If so, that signal may be hiding failed requests.
Ask whether your monitoring would change if error replies began returning 4xx and 5xx codes. Alert thresholds tuned to the old pattern may start firing. That signal would be accurate, and someone should plan for it.
A green dashboard is only useful if the status behind it is honest. This specification gives GraphQL services a shared way to do so, if they follow it.
Produced by the WebPulse Newsroom with AI assistance from the original reporting credited below, and checked against that source by our editorial review. How we use AI.
Original reporting: graphql.org.





