I’m seeing many API developers, specially those that come from a REST background, struggle with GraphQL simply because they are introducing protocol concepts into their GraphQL documents.

GraphQL is not bound to any network protocol, it is most often implemented on top of the HTTP protocol and it only uses the most basic features of HTTP. That is because GraphQL treats HTTP as a dum pipe. Introducing protocol concept such as a 404 Not Found status code into your GraphQL documents will only cause you development pain.

Now, I know what you are thinking, “but I don’t want to reinvent the wheel”, normally you would be correct, after all the http spec takes care of many things that developers often take for granted, things like authorization and caching, but in the case of GraphQL ignoring the HTTP spec is the price of admission to creating a good GraphQL API.