Skip to content

Make 405 RECOMMENDED for mutations over GET#410

Open
martinbonnin wants to merge 29 commits into
mainfrom
405-recommended
Open

Make 405 RECOMMENDED for mutations over GET#410
martinbonnin wants to merge 29 commits into
mainfrom
405-recommended

Conversation

@martinbonnin

Copy link
Copy Markdown
Contributor

The status code paragraph currently reads like this:

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

- If the failure is due to an issue in the request itself, the appropriate `4xx`
  status code should be used:
  - If a mutation is attempted via the `GET` verb, status code `405` MUST 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 and the
    `Accept` header does not include `application/json`, then 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 cannot process the request due to being 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.

I love this paragraph because it gives concrete guidance what error status code to use in 16 real life cases. For 15 of those cases, it gives a RECOMMENDATION, but for the very first case, it gives a REQUIREMENT.

I find this adds unnecessary cognitive load to the spec. I would like to point people at this paragraph and say: "look, this is our recommendation but you can use something else in the 4xx or 5xx range if you want to".

The 405 exception makes everything more complicated because now I have to explain that in that specific case you can't use anything else. And I'm not sure how to explain this.

Question: is there a specific reason we disallow people to use 4xx for mutation over GET but allow it for everything else?

martinbonnin and others added 28 commits June 23, 2026 14:29
* Restore important guidance and recommend support for Accept:application/json

* Reword sentence to make the  exclusion clear

* Clarify another paragraph

* Clarify

* Non-normative recommendation of application/json for successful legacy requests

* Legacy can use any 2xx status code

* Consistent order

* Trim extraneous text
Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
@martinbonnin martinbonnin changed the title Remove MUST requirement for 405 Make 405 RECOMMENDED for mutations over GET Jul 3, 2026
Base automatically changed from legacy-client-editorial to main July 13, 2026 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants