Skip to content

Detail HTTP status codes to use for various error conditions #354

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 1 commit into
base: main
Choose a base branch
from
Open

Detail HTTP status codes to use for various error conditions #354

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 41 additions & 13 deletions spec/GraphQLOverHTTP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -519,8 +519,6 @@ _GraphQL response_, the server SHOULD respond with the appropriate status code
depending on the concrete error condition, and MUST NOT respond with a `2xx`
status code when using the `application/graphql-response+json` media type.

Note: Typically the appropriate status code will be `400` (Bad Request).

Note: This rule is "should" to maintain compatibility with legacy servers which
can return 200 status codes even when this type of error occurs, but only when
not using the `application/graphql-response+json` media type.
Expand Down Expand Up @@ -678,18 +676,48 @@ since no _GraphQL request error_ has occurred it is seen as a "partial
response".

If the _GraphQL response_ does not contain the {data} entry then the server MUST
reply with a `4xx` or `5xx` status code as appropriate.
reply with a `4xx` or `5xx` status code as appropriate:

- If the failure is due to an issue in the request itself, the appropriate `4xx`
status code should be used:
- If an unsupported HTTP method is used, status code `405` is RECOMMENDED.
- If the `Content-Type` of the request is not supported, status code `415` is
RECOMMENDED.
- If none of the media types in the `Accept` header are supported, status code
`406` is RECOMMENDED.
- If the client did not produce a request within the time that the server was
prepared to wait, status code `408` is RECOMMENDED.
- If the size of the URI was too large, status code `414` is RECOMMENDED (and
the client should consider using `POST` instead).
- If the size of the request headers (or any one header) was too large, status
code `431` is RECOMMENDED.
- If the size of the `POST` request body was too large, status code `413` is
RECOMMENDED.
- If the JSON body of the request could not be parsed, status code `400` is
RECOMMENDED.
- If the request is not a well-formed _GraphQL-over-HTTP request_, status code
`422` is RECOMMENDED.
- If the GraphQL document in the request cannot be parsed, status code `400`
is RECOMMENDED.
- If the request does not pass GraphQL validation, status code `422` is
RECOMMENDED.
- If the operation to execute cannot be unambiguously determined, status code
`422` is RECOMMENDED.
- If the variable values cannot be coerced to match the operation's variable
definitions, status code `422` is RECOMMENDED.
- If the client is not permitted to issue the GraphQL request then the server
SHOULD reply with `401`, `403` or similar appropriate status code.
- If the server is a short and stout ceramic vessel, status code `418` is
RECOMMENDED.
- When the server is the reason for failure, the appropriate `5xx` status code
should be used; for example, if the server is not able to execute requests at
this time due to maintenance or load-shedding then status code `503` is
RECOMMENDED.

Note: The GraphQL specification indicates that the only situation in which the
_GraphQL response_ does not include the {data} entry is one in which the
{errors} entry is populated.

If the request is not a well-formed _GraphQL-over-HTTP request_, or it does not
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
Expand Down Expand Up @@ -717,7 +745,7 @@ For example a POST request body of `{"qeury": "{__typename}"}` (note: typo) or
shape for `variables`).

A request that does not constitute a well-formed _GraphQL-over-HTTP request_
SHOULD result in status code `400` (Bad Request).
SHOULD result in status code `422` (Unprocessable Content).

##### Document parsing failure

Expand All @@ -729,20 +757,20 @@ code `400` (Bad Request).
##### Document validation failure

If a request fails _GraphQL validation_, the server SHOULD return a status code
of `400` (Bad Request) without proceeding to GraphQL execution.
of `422` (Unprocessable Content) without proceeding to GraphQL execution.

##### Operation cannot be determined

If [GetOperation()](<https://spec.graphql.org/draft/#GetOperation()>) raises a
_GraphQL request error_, the server SHOULD NOT execute the request and SHOULD
return a status code of `400` (Bad Request).
return a status code of `422` (Unprocessable Content).

##### Variable coercion failure

If
[CoerceVariableValues()](<https://spec.graphql.org/draft/#CoerceVariableValues()>)
raises a _GraphQL request error_, the server SHOULD NOT execute the request and
SHOULD return a status code of `400` (Bad Request).
SHOULD return a status code of `422` (Unprocessable Content).

##### Field errors encountered during execution

Expand Down