GraphQL gets its first official HTTP specification
A new GraphQL over HTTP spec gives servers a dedicated media type and a defined set of status codes, including an unusual one for responses that mix data and errors.
The GraphQL Technical Steering Committee published the first release of a GraphQL over HTTP specification on 12 November. GraphQL has been transport-agnostic since its 2015 release, leaving it up to each server how requests and responses actually travel over the wire. Over HTTP, that gap meant proxies, caches and other intermediaries often couldn’t tell a genuine GraphQL response from an error response passed through by the network, because most servers just replied with plain application/json.
The spec defines a new media type, application/graphql-response+json, and a set of rules for status codes: a 2xx code when the result contains data, 4xx or 5xx when it contains only errors, and 422 Unprocessable Content for request errors such as querying a field that doesn’t exist. For the case where a response contains both data and errors together, the spec calls for a dedicated 294 status code. Servers must support POST; GET is optional and may not be used for mutations. Request batching and persisted queries are both still in progress as follow-up pull requests.
Why it matters: if you build or operate GraphQL APIs, this is the first documented, implementation-independent answer to “what should my server actually send over HTTP”, rather than whatever convention your framework happened to pick. The GraphQL team says most existing frameworks already follow it, so this mostly formalises current behaviour.
The caveat: 294 isn’t a status code anyone’s HTTP client or middleware is likely to recognise yet. Anything that special-cases known 2xx codes, or rejects unfamiliar ones, will need checking against it.