Use 203 as the partial status code

[benjie]

See changes for explanation.

Note: this will need testing before we can merge it.

[BoD]

Is there already work around code 294? A quick search didn't yield any results.

[benjie]

Only what I’ve previously proposed, which has been overwritten by this. Just a new status code really. “94” being “PA” for PArtial 🤷‍♂️

[BoD]

Wondering if a specific header could be added (but not sure which one!) instead of re-using a status code with a different meaning.

My only concern is that intermediaries may interpret 203 in unexpected ways.

[phryneas]

(removed, discussed later in the RFC text anyways)

[phryneas]

I'm not sure it needs to be read like that.

Later in section 6.1.1, they keep an open door for extension:

HTTP status codes are extensible. HTTP applications are not required
to understand the meaning of all registered status codes, though such
understanding is obviously desirable. However, applications MUST
understand the class of any status code, as indicated by the first
digit, and treat any unrecognized response as being equivalent to the
x00 status code of that class, with the exception that an
unrecognized response MUST NOT be cached. For example, if an
unrecognized status code of 431 is received by the client, it can
safely assume that there was something wrong with its request and
treat the response as if it had received a 400 status code. In such
cases, user agents SHOULD present to the user the entity returned
with the response, since that entity is likely to include human-
readable information which will explain the unusual status.

Additional status codes that are not part of section 10 are defined in RFC 6585, which officially Updates: 2616.
But new status codes are also defined outside of the scope of 2616, e.g. status code 207 is defined in RFC4918 without any mention of "updating" RFC 2616, it's only referenced in different context there.

So, going by that, we wouldn't necessarily be restricted to the RFC 2616 status codes - but of course, introducing a new one might bring it's own risk.

That said, RFC 4918 reads to me like it only applies to very specific contents types, so maybe 207 with a different content type might actually not provoke a conflict?

A Multi-Status response conveys information about multiple resources
in situations where multiple status codes might be appropriate. The
default Multi-Status response body is a text/xml or application/xml
HTTP entity with a 'multistatus' root element. Further elements
contain 200, 300, 400, and 500 series status codes generated during
the method invocation. 100 series status codes SHOULD NOT be recorded
in a 'response' XML element.

[Shane32]

My thoughts:

203 Non-Authoratative Information

Benefits:

• Proxies, firewalls and clients are unlikely to refuse a document because the code is 203; this would be a normal and expected status code to see, which does not imply any improper behavior.

Cons:

• Name and description do not have any relation to GraphQL partial response
• Proxies may be in use along a HTTP communication path, and may change responses to 203 or consume it. However, for server side logging, it doesn't matter what a proxy does with the status code after it's left the server

206 Partial Content

Benefits:

• Name somewhat matches intended use

Cons:

• Proxies, firewalls or even clients may attempt to validate the content, and (1) seeing no Content-Range response header, or (2) not expecting a partial response, reject the request

207 Multi-Status

Benefits:

• Name and description closely matches intended use
  • Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations.
• The status code is commonly in use and should be supported by proxies and firewalls
• The status code is defined in WebDAV's RFC, layered under HTTP, and not the HTTP protocol itself, much the same way this GraphQL RFC is layered under the HTTP protocol. As such, proxies should be oblivious to the content and pass along the request.

Cons:

• Firewalls may attempt to validate the content type of data returned with a 207 response type (at a minimum), and finding it is not XML, reject the response.

294 Partial Response (or another GraphQL-defined code)

Benefits:

• No overlap with other status codes
  • Logging providers can choose to recognize 294 as a GraphQL-specific response code

Cons:

• Firewalls may reject responses with this unrecognized status code
• Exactly duplicates the purpose of status code 207
• Getting IANA approval for a new officially recognized status code may prove difficult, given the presence of 207

[Shane32]

It should be noted that since most all requests will be HTTPS, the above firewall considerations only apply to application-level firewalls (Secure Web Gateway), as regular firewalls would not have access to the response code.

[Shane32]

I would select 207 because its exact description matches our use case. But first I would prefer to see some testing with commonly used Secure Web Gateways. I wouldn't worry about server-end proxies because the GraphQL server operator would set that up as needed (which may include changing the response code of the GraphQL server to always be 200). And the use of Secure Web Gateways are probably limited to large companies or governments which are likely enough to have a team ready to allow (or disallow) access to specific websites. So testing becomes less important. The only leaves other proxies, such as a cell provider might install to make their network appear faster, which I don't think proxies would be an issue with 207. So I'd go with 207. (Just my two cents.)

203 is probably the "safest" choice....

[Shane32]

Note that 201/202 also are as "safe" of a selection as 203, perhaps moreso. But again, the meaning doesn't carry over to GraphQL's intended use at all.

[Keweiqu]

Super excited we are exploring this! This has been a very common pain points for new Apps adopting GraphQL from REST. Very often, we hear developers complain about everything is 200s, and their reliability metrics from REST can't be reused anymore. This effort would be a great help to mitigate this pain point

[bclozel]

While 203 sounds safest from a proxy perspective, anyone encountering this status in production (without particular GraphQL knownledge) and checking the MDN for HTTP 203 would be confused. They would think that an HTTP proxy in their infrastructure has modified the headers or the response body. So I agree with @Shane32 on that one, it's important that the HTTP semantics match the GraphQL intent.

207 is definitely a closer match. Right now the MDN shows an example of a WebDav response with the status information enclosed. I think several GraphQL implementations do convey similar information as error extensions (for example, graphql-java's. ErrorType). I'm wondering if promoting this information at the error map level in the main graphql spec would align with this choice. What's your opinion?

I'm ruling out 206 (because of Content-Range) and 294 (for reasons explained in previous comments).

Taking a step back, I think that one of the goals of this spec is to make information about the GraphQL exchanges "leak" as much as possible in the HTTP transport when semantics match; this would help existing tools and newcomers to better understand what's happening without having to parse the actual document. Even if HTTP proxies work fine with the chosen HTTP status, I'm wondering if existing observability tools/dashboards/etc. will really consider another 20x in a different fashion. For example, if responding with HTTP 207 somehow breaks observability dashboards and confuses tools, then this would be a net negative for production usage.

[benjie]

if responding with HTTP 207 somehow breaks observability dashboards and confuses tools, then this would be a net negative for production usage.

This was my main concern with using 207 - it seems 100% related to WebDAV and thus tools may not expect it to be used elsewhere, may expect it to contain XML, and might even try and parse the XML.

Further, I'd argue that 207 doesn't align completely with GraphQL's partial success; it's defined in RFC4918 as:

The 207 (Multi-Status) status code provides status for multiple independent operations

i.e. it's more designed for batched processing rather than GraphQL's nested (and dependent/chained) resolution model.

I agree that 203 doesn't align semantically 100% (though I think there is a little more than 0% alignment - if errors occur then the data returned is kind of non-authoritative because you couldn't actually retrieve all the data), but I'm still leaning towards it from a compatibility POV.

---

Here's a summary from my POV:

❌ 201 Created - explicitly means "created" and I think it might be useful in future (e.g. for creating a continuable streaming endpoint to represent a subscription or incremental delivery) so I wanted to avoid using that. Moreover it seems 100% inappropriate for use in query operations with no side effects.

❌ 202 Accepted - explicitly means it has not been completed - not appropriate.

🤷‍♂️ 203 Non-Authoritive Information - slight alignment (due to errors - the authoritive data isn't available) and doesn't have any expectations.

❌ 204 No Content - definitely doesn't work!

❌ 205 Reset Content - no content

❌ 206 Partial Content - Requires Range header - not appropriate.

🤔 207 Multi-Status - stronger (but still loose) alignment, tightly tied to WebDAV, has many expectations

❌ 208 Already Reported - inappropriate

🥺 294 Partial Success - 100% semantic alignment because it specifically means "partial success" in the GraphQL sense; no existing tooling expectations, HTTP RFC says to treat as success, unlikely to conflict with other uses, may be a challenge to standardize

---

Ideally, rather than opining on this, we should actually test it - we need to find out how well the various status codes work with native HTTP clients in different environments (browser, android, iOS, various server-side programming languages, desktop apps, etc), different proxies (including things like Cloudflare), different API gateways, different observability tooling, IDSes, etc. Ideally this would be crowd-sourced.

Alternatively we just pick one and see what happens. If we're picking one I would either pick 203 (has the least risk of conflict) or 294 (explicit new status code). I could be convinced to use 207 if it were demonstrated that it doesn't break existing tooling (and that 294 does).

People do make and use their own HTTP status codes, a number of these can be seen on Wikipedia, so I don't think we should 100% count it out.