Skip to content

Use 294 as the partial status code #346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Use 294 as the partial status code #346

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
970d434
Use 203 as the partial status code
benjie May 8, 2025
05182f5
Overhaul massive inline note by moving much to section 7
benjie May 8, 2025
313cebd
spec-md formatting
benjie May 8, 2025
f2552ac
Replace 203 status code with 294
benjie Jun 2, 2025
8beaddf
Typo
benjie Jun 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 60 additions & 25 deletions spec/GraphQLOverHTTP.md
View file
Original file line number Diff line number Diff line change
@@ -647,32 +647,41 @@ should be added to the above.

### application/graphql-response+json

This section only applies when the response body is to use the
This section only applies when the response body uses the
`application/graphql-response+json` media type.

With this media type, clients should process the response as a well-formed
_GraphQL response_ independent of the HTTP status code, and should read the
response body (specifically {data} and {errors}) to determine the status of the
response.

Note: The purpose of setting a status code is to aid intermediary services and
tooling (which may not implement this specification) in understanding the rough
status of a response. This is useful in request logs, anomaly and intrusion
detection, metrics and observability, API gateways, and more. The status code is
not intended to aid the client, in fact it is recommended the client ignore the
status code when this media type is in use.

If the _GraphQL response_ contains the {data} entry and it is not {null}, then
the server MUST reply with a `2xx` status code and SHOULD reply with `200`
status code.
the server MUST reply with a `2xx` status code.

If the _GraphQL response_ contains the {data} entry and does not contain the
{errors} entry, then the server SHOULD reply with `200` status code.

Note: There are no circumstances where the GraphQL specification allows for a
response having {data} as {null} without {errors} being present.

If the _GraphQL response_ contains both the {data} entry (even if it is {null})
and the {errors} entry, then the server SHOULD reply with `203` status code.

Note: The result of executing a GraphQL operation may contain partial data as
well as encountered errors. Errors that happen during execution of the GraphQL
operation typically become part of the result, as long as the server is still
able to produce a well-formed _GraphQL response_. There's currently not an
approved HTTP status code to use for a "partial response," contenders include
WebDAV's status code "207 Multi-Status" and using a custom code such as "247
Partial Success."
[IETF RFC2616 Section 6.1.1](https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1)
states "codes are fully defined in section 10" implying that though more codes
are expected to be supported over time, valid codes must be present in this
document.

If the _GraphQL response_ contains the {data} entry and it is {null}, then the
server SHOULD reply with a `2xx` status code and it is RECOMMENDED it replies
with `200` status code.

Note: Using `4xx` and `5xx` status codes in this situation is not recommended -
since no _GraphQL request error_ has occurred it is seen as a "partial
response".
able to produce a well-formed _GraphQL response_. For details of why status code
`203` is recommended, see [Partial success](#sec-Partial-success). Using `4xx`
and `5xx` status codes in this situation is not appropriate - since no _GraphQL
request error_ has occurred it is seen as a "partial response" or "partial
success".

If the _GraphQL response_ does not contain the {data} entry then the server MUST
reply with a `4xx` or `5xx` status code as appropriate.
@@ -687,12 +696,6 @@ pass validation, then the server SHOULD reply with `400` status code.
If the client is not permitted to issue the GraphQL request then the server
SHOULD reply with `403`, `401` or similar appropriate status code.

Note: When the response media type is `application/graphql-response+json`,
clients can rely on the response being a well-formed _GraphQL response_
regardless of the status code. Intermediary servers may use the status code to
determine the status of the _GraphQL response_ without needing to process the
response body.

#### Examples

The following examples provide guidance on how to deal with specific error cases
@@ -782,6 +785,38 @@ is met:
- the response media type is `application/graphql-response+json`, or
- the status code is `200`.

## Partial success

The result of executing a GraphQL operation may contain partial data as well as
encountered errors. Errors that happen during execution of the GraphQL operation
typically become part of the result, as long as the server is still able to
produce a well-formed _GraphQL response_.

Using `4xx` and `5xx` status codes when {data} is present and non-null is not
appropriate; since no _GraphQL request error_ has occurred it is seen as a
"partial response" or "partial success".

There's currently not an approved official HTTP status code to use for a
"partial success," contenders include "206 Partial Content" (which requires the
`Range` header), WebDAV's status code "207 Multi-Status", and using a custom
code such as "294 Partial Success."

[IETF RFC2616 Section 6.1.1](https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1)
states "codes are fully defined in section 10" implying that though more codes
are expected to be supported over time, valid codes must be present in this
document. For compatibility reasons, using HTTP status `203` which has no
Copy link

@phryneas phryneas May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

additional requirements seems to work the best with intermediate servers and
clients, but since it does not semantically line up we only recommend its usage
alongside the `application/graphql-response+json` media type which makes the
meaning explicit. We hope to one day move to `294` if someone can push it
through the IETF review process.

Note: This use of HTTP 203 does not strictly align with the intended semantics
of this status code, but was a pragmatic choice to maximize compatibility whilst
allowing servers to indicate partial success such that intermediaries that do
not implement this specification may still track the not-fully-successful
request (for example, for observability).

## Security

This specification focuses solely on the intersection of GraphQL and HTTP.